yiisoft · samdark · Mar 25, 2026 · Mar 24, 2026 · Mar 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 ## 1.1.1 under development
 
-- no changes in this release.
+- Enh #305: Add `tabIndex()` method to `Button` widget (@Mister-42)
 
 ## 1.1.0 March 06, 2026
 

diff --git a/src/Button.php b/src/Button.php
@@ -472,6 +472,28 @@
         return $this->addClass($size?->value);
     }
 
+    /**
+     * The `tabindex` attribute indicates that its element can be focused, and where it participates in sequential
+     * keyboard navigation (usually with the Tab key, hence the name).
+     *
+     * It accepts an integer as a value, with different results depending on the integer's value:
+     *
+     * - A negative value (usually `tabindex="-1"`) means that the element is not reachable via sequential keyboard
+     *   navigation, but could be focused with JavaScript or visually. It's mostly useful to create accessible widgets
+     *   with JavaScript.
+     * - `tabindex="0"` means that the element should be focusable in sequential keyboard navigation, but its order is
+     *   defined by the document's source order.
+     * - A positive value means the element should be focusable in sequential keyboard navigation, with its order
+     *   defined by the value of the number. That is, `tabindex="4"` is focused before `tabindex="5"`, but after
+     *   `tabindex="3"`.
+     *
+     * @link https://html.spec.whatwg.org/multipage/interaction.html#attr-tabindex
+     */
+    public function tabIndex(?int $value): self
+    {
+        return $this->attribute('tabindex', $value);
+    }
+
     /**
      * Sets the toggle behavior by the `data-bs-toggle` attribute, enabling interactive functionality such as `button`,
      * `dropdown`, `modal`, and `tooltip`.
@@ -506,7 +528,7 @@
    {
        $new = clone $this;
        $new->tag = match ($type) {
            ButtonType::LINK => A::tag(),
            ButtonType::RESET => ButtonTag::reset(''),
            ButtonType::RESET_INPUT => Input::resetButton(),
            ButtonType::SUBMIT => ButtonTag::submit(''),
@@ -562,7 +584,7 @@
    {
        $attributes = $this->attributes;
        $classes = $attributes['class'] ?? null;
        $tag = $this->tag ?? ButtonTag::tag()->button('');

        unset($attributes['class'], $attributes['id']);


diff --git a/tests/ButtonTest.php b/tests/ButtonTest.php
@@ -726,4 +726,18 @@ public function testVariant(?ButtonVariant $buttonVariant, string $expected): vo
                 ->render(),
         );
     }
+
+    public function testTabIndex(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <button type="button" class="btn btn-secondary" tabindex="42">Send</button>
+            HTML,
+            Button::widget()
+                ->id(false)
+                ->label('Send')
+                ->tabIndex(42)
+                ->render(),
+        );
+    }
 }