ToggleGroup

Compact single- or multi-select choice set rendered as connected toggles.

Preview

A live, theme-aware example rendered with the published component.

Loading preview…

Import

Import from the focused entry point below, or use the same named export from @tavojs/ui. Both are public APIs; measure the built application when comparing their bundle cost.

TSX

tsximport { ToggleGroup } from "@tavojs/ui/toggle-group";

The component import loads compiled component CSS. Enable tavoUi() for your project theme variables, or import @tavojs/ui/theme.css once for the package default theme. The equivalent CSS-safe component alias is @tavojs/ui/css/toggle-group.

When to use

Use it when

Use ToggleGroup for choices such as view mode, alignment, density, or active tools when labels are short and options fit on one line.

Choose something else when

Use Tabs when selection changes a labelled content panel, RadioGroup for conventional form choices, and Select when space is constrained or options are numerous.

Examples

These examples include imports and local state where interaction requires it. Render the exported component in a page after completing UI installation. Demo state stays in the mounted component; connect file handling, persistence, and data loading to your application as needed.

ToggleGroup example

TSXCreate: src/components/examples/ToggleGroupExample1.tsx

tsximport { createTavo } from "@tavojs/core";
import { ToggleGroup } from "@tavojs/ui/toggle-group";
import { Text } from "@tavojs/ui";

type State = { view: string };

export const ToggleGroupExample1 = createTavo<Record<string, never>, State>({
  model: () => ({ view: "grid" }),
  view: ({ state, model }) => (
    <>
      <ToggleGroup aria-label="View mode">
        <ToggleGroup.Item
          name="view"
          value="list"
          label="List"
          checked={state.view === "list"}
          onChange={() => model.set("view", "list")}
        />
        <ToggleGroup.Item
          name="view"
          value="grid"
          label="Grid"
          checked={state.view === "grid"}
          onChange={() => model.set("view", "grid")}
        />
      </ToggleGroup>
      <Text>Current view: {state.view}</Text>
    </>
  )
});

Common props and defaults

A curated starting point. The complete TypeScript API below includes additional props and compound member contracts.

Prop	Type	Default	Description
`className`	`string`	—	Optional class hook applied to the public root element owned by the component.
`name`	`string`	—	Configures name for this component.
`value`	`string \| string[]`	—	Configures value for this component.
`defaultValue`	`string \| string[]`	—	Configures defaultValue for this component.
`items`	`{ label: Child; value: string; accessibleLabel?: string; title?: string; disabled?: boolean }[]`	—	Configures items for this component.
`type`	`"single" \| "multiple"`	—	Configures type for this component.
`allowEmpty`	`boolean`	—	Configures allowEmpty for this component.
`fullWidth`	`boolean`	—	Configures fullWidth for this component.
`onValueChange`	`(value: string \| string[] \| undefined) => void`	—	Configures onValueChange for this component.

Complete TypeScript API

Import from @tavojs/ui/toggle-group. Published exports: ToggleGroup, ToggleGroupItem, ToggleGroupItemComponent, ToggleGroupItemProps, ToggleGroupProps, ToggleGroupRoot, ToggleGroupValue.

`ToggleGroupProps`

Property	Type	Required	Description
`className`	`string`	No	Optional class hook applied to the public root element owned by the component.
`name`	`string`	No	Configures name for this component.
`value`	`string \| string[]`	No	Configures value for this component.
`defaultValue`	`string \| string[]`	No	Configures defaultValue for this component.
`items`	`ToggleGroupItem[]`	No	Configures items for this component.
`type`	`"single" \| "multiple"`	No	Configures type for this component.
`size`	`Size`	No	Inherited size attribute accepted by ToggleGroup.
`variant`	`ToggleVariant`	No	Inherited variant attribute accepted by ToggleGroup.
`fullWidth`	`boolean`	No	Configures fullWidth for this component.
`allowEmpty`	`boolean`	No	Configures allowEmpty for this component.
`onValueChange`	`(value: ToggleGroupValue) => void`	No	Configures onValueChange for this component.

`ToggleGroupItemProps`

Property	Type	Required	Description
`children`	`Child`	No	Inherited children attribute accepted by ToggleGroup.
`className`	`string`	No	Optional class hook applied to the public root element owned by the component.
`sx`	`Sx`	No	Inherited sx attribute accepted by ToggleGroup.
`id`	`string`	No	Inherited id attribute accepted by ToggleGroup.
`role`	`string`	No	Inherited role attribute accepted by ToggleGroup.
`style`	`Record<string, unknown>`	No	Inherited style attribute accepted by ToggleGroup.
`title`	`string`	No	Inherited title attribute accepted by ToggleGroup.
`tabIndex`	`number`	No	Inherited tabIndex attribute accepted by ToggleGroup.
`hidden`	`boolean`	No	Inherited hidden attribute accepted by ToggleGroup.
`disabled`	`boolean`	No	Inherited disabled attribute accepted by ToggleGroup.
`onClick`	`TavoEventHandler<MouseEvent>`	No	Inherited onClick attribute accepted by ToggleGroup.
`onChange`	`TavoEventHandler<Event>`	No	Inherited onChange attribute accepted by ToggleGroup.
`onInput`	`TavoEventHandler<Event>`	No	Inherited onInput attribute accepted by ToggleGroup.
`onKeyDown`	`TavoEventHandler<KeyboardEvent>`	No	Inherited onKeyDown attribute accepted by ToggleGroup.
`onFocus`	`TavoEventHandler<FocusEvent>`	No	Inherited onFocus attribute accepted by ToggleGroup.
`onBlur`	`TavoEventHandler<FocusEvent>`	No	Inherited onBlur attribute accepted by ToggleGroup.
`label`	`Child`	No	Inherited label attribute accepted by ToggleGroup.
`value`	`string`	Yes	Configures value for this component.
`name`	`string`	No	Configures name for this component.
`type`	`"single" \| "multiple"`	No	Configures type for this component.
`checked`	`boolean`	No	Inherited checked attribute accepted by ToggleGroup.
`defaultChecked`	`boolean`	No	Inherited defaultChecked attribute accepted by ToggleGroup.
`accessibleLabel`	`string`	No	Inherited accessibleLabel attribute accepted by ToggleGroup.
`size`	`Size`	No	Inherited size attribute accepted by ToggleGroup.
`variant`	`ToggleVariant`	No	Inherited variant attribute accepted by ToggleGroup.

State ownership and DOM target

Concern	Contract
State	Use value to supply rendered state. Update it through the documented callback or native event handler. For browser-owned initial values, use defaultValue instead.
DOM target	Native input attributes target the owned form control; wrapper-specific props stay on the documented component root.

Anatomy and related components

Public compound members: Root, Item

Limitations

Use Tabs when selection changes a labelled content panel, RadioGroup for conventional form choices, and Select when space is constrained or options are numerous.

Use only the documented props, entry points, and compound members. Internal DOM nesting and CSS class names can change without becoming part of the public component contract.

Accessibility

Form components pass through native attributes and should be paired with visible labels or accessible names.

Use Field, FormLabel, FormControlLabel, or aria-label for labeling.
Preserve native input semantics whenever possible.
Expose validation with error text and aria-invalid where relevant.

Component status

Contract	Current value
Maturity	stable
Category	forms
Component import	`@tavojs/ui/toggle-group`
Explicit CSS import	`@tavojs/ui/css/toggle-group`
Preview	Interactive preview available on this page