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 the component from its dedicated entry point to keep the dependency and generated bundle explicit.

TSX

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

Normal Tavo.js applications load component styles through the Tavo.js UI plugin. If the application manages component CSS manually, also import @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

ToggleGroup example

TSX

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

export function ToggleGroupExample1() {
  return (
    <>
      <ToggleGroup
        name="view"
        value="grid"
        items={[{ label: "List", value: "list" }, { label: "Grid", value: "grid" }]}
      />
    </>
  );
}

Common props and defaults

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.
`items`	`{ label: string; value: string; disabled?: boolean }[]`	Required	Configures items for this component.
`type`	`"single" \| "multiple"`	—	Configures type for this component.
`size`	`Size`	—	Configures size for this component.
`variant`	`"default" \| "outline" \| "ghost"`	—	Configures variant for this component.

Complete TypeScript API

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

`ToggleGroupProps`

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.
`name`	`string`	No	Configures name for this component.
`value`	`string \| string[]`	No	Configures value for this component.
`items`	`ToggleGroupItem[]`	Yes	Configures items for this component.
`type`	`"single" \| "multiple"`	No	Configures type for this component.
`size`	`Size`	No	Configures size for this component.
`variant`	`ToggleVariant`	No	Configures variant for this component.

State ownership and DOM target

Concern	Contract
State	Application controlled through value and the matching callback.
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