Segmented Control

The <x-wirekit::segmented-control> component is a pill-style radio group for switching between a small set of mutually exclusive options. It uses role="radiogroup" with role="radio" on each segment, providing full keyboard navigation via arrow keys.

Basic Usage

<x-wirekit::segmented-control
    label="View"
    name="view"
    :options="['grid' => 'Grid', 'list' => 'List', 'table' => 'Table']"
    value="grid"
/>

Without Preselected Value

<x-wirekit::segmented-control
    label="Period"
    name="period"
    :options="['day' => 'Day', 'week' => 'Week', 'month' => 'Month', 'year' => 'Year']"
/>

Size Variants

<x-wirekit::stack gap="md">
    <x-wirekit::segmented-control label="Small" name="s-sm" size="sm" :options="['a' => 'One', 'b' => 'Two', 'c' => 'Three']" value="a" />
    <x-wirekit::segmented-control label="Medium" name="s-md" size="md" :options="['a' => 'One', 'b' => 'Two', 'c' => 'Three']" value="a" />
    <x-wirekit::segmented-control label="Large" name="s-lg" size="lg" :options="['a' => 'One', 'b' => 'Two', 'c' => 'Three']" value="a" />
</x-wirekit::stack>

Narrow Screens

When the options are wider than the space the control sits in, the bar scrolls on its own instead of widening the page, the way tabs do, and the selected option is scrolled into view when the page loads. A soft shadow at an edge says more options sit past it, and it moves to the other edge as the bar scrolls. Each option keeps its label on one line. The preview below fits on a wide screen; at phone width the bar scrolls.

<x-wirekit::segmented-control
    label="Orders"
    name="orders"
    :options="['all' => 'All orders', 'awaiting' => 'Awaiting payment', 'fulfill' => 'To fulfill', 'shipped' => 'Shipped', 'completed' => 'Completed']"
    value="completed"
/>

Translations lengthen labels, so a bar that fits in one language can overflow in the next. Keep labels short all the same: a set of options a phone cannot show at once is easier to use as tabs or a select.

Options in Another Language

An option can be an array with its label and the lang its words are in, the shape select takes. A choice of languages names each one in its own language, and the lang makes a screen reader say it in that language's voice instead of the page's. Plain value => label options and arrays mix freely.

<x-wirekit::segmented-control
    label="Language"
    name="interface-language"
    :options="[
        'en' => ['label' => 'English', 'lang' => 'en'],
        'de' => ['label' => 'Deutsch', 'lang' => 'de'],
        'fr' => ['label' => 'Français', 'lang' => 'fr'],
    ]"
    value="en"
/>

Livewire Integration

<x-wirekit::segmented-control
    label="Sort"
    name="sort"
    :options="['newest' => 'Newest', 'oldest' => 'Oldest', 'popular' => 'Popular']"
    :value="$sortOrder"
    wire:model.live="sortOrder"
/>

The selected value is submitted via a hidden <input type="hidden"> — wire:model binds to it automatically. Pass the bound property as :value as well: the control keeps the selected segment in its own state, seeded from value, so without it a stored choice is not shown and a value the server sets does not move the selection.

Bound to a property declared int, float or an enum backed by int, the hidden input is read as a number: wire:model.live goes out as wire:model.number.live. It holds the segment as text, and Livewire would take the server's typed answer to that text for a change made on the server and write it over a segment chosen while the request was out. A property without a type, or a string one, gets the text.

Optimistic UI

Pass the name of the Livewire method the control should call and the segment moves immediately, then confirms or undoes itself when the server answers:

<x-wirekit::segmented-control
    name="tier"
    label="Tier"
    :value="$tier"
    :options="['basic' => 'Basic', 'plus' => 'Plus', 'max' => 'Max']"
    optimistic="chooseTier"
/>

Load wirekit-optimistic.js alongside whichever bundle you already use — below it, in your layout:

@wirekitScripts
<script src="{{ asset('vendor/wirekit/wirekit-optimistic.js') }}" defer></script>

Try it

The demo below runs the real path: the change shows immediately, the outline says it is provisional, and the server's answer either confirms it silently or takes it back.

{{-- In your app there is no host: your own Livewire component owns the method. --}}
<x-wirekit::segmented-control
    name="tier"
    label="Tier"
    :value="$tier"
    :options="['basic' => 'Basic', 'plus' => 'Plus', 'max' => 'Max']"
    optimistic="chooseTier"
/>

The <livewire:demos.…> wrapper above exists only on this site — it supplies the demo methods so the page can show a real round trip. The block under it is what you write.

The prop takes a method name rather than true because the component cannot know the action otherwise: server actions reach a WireKit component through the attribute bag, so it never sees your wire:click. optimistic replaces wire:model.live here rather than joining it — the method you name is what changes the value on the server; pass the current one with :value so the control knows where it started.

Arrow keys go through the same path as a click: selection follows focus in a radio group, so moving with the keyboard is a pick like any other and behaves identically.

<x-wirekit::segmented-control
    label="View"
    name="view"
    :options="['grid' => 'Grid', 'list' => 'List', 'table' => 'Table']"
    value="grid"
    hint="Arrow keys move between the options."
    error="Table view is unavailable while the export is running."
/>

Props

Slots

Accessibility

• Outer container: role="radiogroup" with aria-label from the label prop
• Each segment: role="radio" with aria-checked="true" / "false"
• An autofocus written on the tag goes to the selected segment, which holds the tab stop
• Selection change announced automatically by screen readers via the radio role semantics
• The selected segment is a raised surface in --font-wk-selected-weight. The surface marks it on its own, so a theme may set that weight to the body weight. Under forced colors, where the surface and its shadow are not painted, the selected segment is framed in the system's selection color
• Disabled state sets aria-disabled="true" on the radiogroup and each segment
• Focus ring is visible on the focused segment via focus-visible styling
• Every segment keeps the 24px minimum target of WCAG 2.5.8 in all three sizes, whatever size your theme gives the text — --size-wk-target-min sets the floor

Keyboard Interaction

Selection follows focus, and both arrow axes wrap at the ends — the same behavior a native radio group has.

The component uses roving tabindex — only the active segment has tabindex="0".

Pitfalls

• Keep the options to a handful. On a narrow screen the bar scrolls instead of widening the page (see Narrow Screens), but an option a reader has to scroll to find is easier to reach in <x-wirekit::tabs> or <x-wirekit::select>.

Design Tokens

Customization

Override defaults in config/wirekit.php:

'components' => [
    'segmented-control' => ['size' => 'md'],
],

Further Reading

• WAI-ARIA: Radiogroup Pattern
• MDN: role="radiogroup"
• MDN: role="radio"
• MDN: aria-checked
• MDN: Roving tabindex