Skip to content
Porcelana

ToggleGroup

Segmented control for picking one or several options.

Example

Example.tsx
import { ToggleGroup, ToggleGroupItem } from "@porcelana/ui";

export default function Example() {
  return (
    <ToggleGroup type="single" defaultValue="week" aria-label="Range">
      <ToggleGroupItem value="day">Day</ToggleGroupItem>
      <ToggleGroupItem value="week">Week</ToggleGroupItem>
      <ToggleGroupItem value="month">Month</ToggleGroupItem>
    </ToggleGroup>
  );
}

Import

Import
import { ToggleGroup, ToggleGroupItem } from "@porcelana/ui";
import "@porcelana/ui/styles.css"; // once, at your app root

Props

Generated from the TypeScript types. Standard HTML attributes are passed through and not listed.

ToggleGroup

PropTypeDefaultDescription
typerequired"single" | "multiple"–Button type (defaults to "button").
aria-labelstring–Defines a string value that labels the current element. @see aria-labelledby.
asChildboolean–Render the single child element instead, merging props and behaviour onto it.
blockboolean–Stretch items to fill the width (good on phones).
defaultValuestring | string[]–The value of the item that is pressed when initially rendered. Use `defaultValue` if you do not need to control the state of a toggle group. The value of the items that are pressed when initially rendered. Use `defaultValue` if you do not need to control the state of a toggle group.
dirDirection–Reading direction for keyboard navigation ("ltr" or "rtl").
disabledboolean–Whether the group is disabled from user interaction. @defaultValue false
idstring–Element id. Generated automatically when omitted.
loopboolean–Whether keyboard navigation wraps from the last item to the first.
onValueChange((value: string) => void) | ((value: string[]) => void)–The callback that fires when the value of the toggle group changes. The callback that fires when the state of the toggle group changes.
orientationOrientation–Layout and arrow-key direction.
rovingFocusboolean–Whether the group should maintain roving focus of its buttons. @defaultValue true
valuestring | string[]–The controlled stateful value of the item that is pressed. The controlled stateful value of the items that are pressed.

ToggleGroupItem

PropTypeDefaultDescription
aria-labelstring–Defines a string value that labels the current element. @see aria-labelledby.
asChildboolean–Render the single child element instead, merging props and behaviour onto it.
disabledboolean–Prevents interaction and dims the control.
idstring–Element id. Generated automatically when omitted.
type"button" | "submit" | "reset"–Button type (defaults to "button").
valuestring | string[]–The controlled stateful value of the item that is pressed. The controlled stateful value of the items that are pressed.

Accessibility

  • type="single" behaves like a radio group; type="multiple" like toggle buttons.
  • Give the group an aria-label.

Mobile

  • block stretches items to the full width; long groups scroll sideways instead of overflowing.