A row of related Toggles that changes values or tool states. Without multiple, it chooses one layout or filter; with multiple, it groups independent on/off tools. Use Tabs when each choice activates a corresponding content panel.
import { Separator, Toggle, ToggleGroup } from "@usememos/ui";
import { Bold, Code, Italic } from "lucide-react";
<ToggleGroup value={[filter]} onValueChange={([next]) => next && setFilter(next)} aria-label="Show">
<Toggle value="all">All</Toggle>
<Toggle value="pinned">Pinned</Toggle>
<Toggle value="archived">Archived</Toggle>
</ToggleGroup>
<ToggleGroup multiple value={marks} onValueChange={setMarks} aria-label="Formatting">
<Toggle value="bold" icon={<Bold />} aria-label="Bold" />
<Toggle value="italic" icon={<Italic />} aria-label="Italic" />
<Separator orientation="vertical" />
<Toggle value="code" icon={<Code />} aria-label="Code" />
</ToggleGroup>| Part | Base UI part | Renders |
|---|---|---|
ToggleGroup |
ToggleGroup |
A <div role="group">. Takes size. Without multiple, adds the selected key |
Toggle |
Toggle |
One item, a <button aria-pressed> |
Separator |
Separator |
A line between clusters, multiple groups only |
interface ToggleGroupProps extends BaseToggleGroup.Props {
size?: Size; // passed to every Toggle inside
fullWidth?: boolean; // fills the container; labeled Toggles grow from their natural width
}Base UI's props pass through: value, defaultValue, onValueChange, multiple, disabled, orientation, loopFocus. The value is always an array of pressed values, even without multiple.
- Give the group an
aria-label. - A single choice among peers is a flat selected fill in a well; an on/off state is a pressed toggle. Never mix the two in one row.
- Without
multiple: filters and layout preferences for the same content, such as All / Pinned / Archived or List / 2 / 3 / Auto. Saving the preference does not turn it into a tab; the choice still changes a value rather than activating a content panel. - With
multiple: independent tools or filters that can be active together, such as Bold and Italic. Tabs always chooses one content panel and does not replace this behavior. - Single-choice ToggleGroups and Tabs reuse the same segmented treatment. Keep the behavior APIs separate; do not add a
multiplemode to Tabs or fake panels for settings. - When long translated options would need several lines in a narrow panel, use a Select. Wrapping keeps a constrained group readable; it is not a reason to force every choice into a segmented group.
- Base UI lets people press the chosen item to clear it. When one item must stay chosen, ignore an empty value, as in the example.
- Arrow keys move focus between items; Space or Enter presses one.
- Set
fullWidthwhen the group is the only control on its row and should line up with the edges, such as a view switch across a popover. Don't setclassName="w-full"andflex-1on the Toggles yourself.
- At most as wide as its container. With
fullWidth, exactly as wide: labeled Toggles start at their natural width and share the extra space equally (flex: 1 1 auto), so equal labels give equal Toggles and a long label is never cut while there is room. Inside a popup that sizes to its content, the group is as wide as its labels need. Labels wrap at word boundaries, and the group and key grow to fit. Items keep enough width for their longest word, icon and padding; when those minimum widths cannot fit together, the group scrolls horizontally instead of breaking words or widening the page. Icon-only items keep their size. Prefer a Select when a narrow panel regularly needs this fallback. multiple: items 2px apart, using Toggle'swellfill andtextwhen on, with no visible border in normal colors. Keyboard focus stays separate from selection.- Inside a segmented key, the label's line box can tighten at xs and sm to leave room for the focus border without changing geometry; its font size stays in the size row. Long labels wrap and increase the group's height.
- Use the existing
mdsize for a labeled layout choice at the top of a settings popover: a 32px group, 28px selected face and 16px icons. Keepsm(24px) for dense contexts; do not invent a height between the size rows. - Without
multiple: a quietwelland contrastingkeyfill, with no visible group or selected-key border in normal colors. The selected label and icon usetext; hover only changes label and icon contrast, without adding a fill or moving the key. Focus reusesmu-focus; do not add a component-specific focus treatment. In forced colors the selected key retains its text-colored border. The key updates immediately and re-measures when an item changes width. Selection and label changes do not animate. Items keep the same dimensions and hit boundaries on every input device.