React Toggle Component Examples

The simplest use is one standalone toggle that tracks its own on/off state. Drop in a Toggle with a label and an icon-as-component child, and it manages its pressed state internally with useState — no wiring required. Each click flips the state, sets aria-pressed for assistive tech, and toggles the data-[state=on] attribute that drives the active styling.

For controlled use, pass a pressed prop and an onChange callback to drive the state from your own store; for uncontrolled use, pass defaultPressed to set the starting value and let the component own it from there. This is the canonical pattern for a single boolean control that should read as a button rather than a checkbox — a "Bold" button in an editor toolbar, a "Pin" toggle on a card, a "Mute" control. The icon sits left of the label with the base style's gap-2.

To let exactly one toggle be active at a time — the text-alignment pattern — wrap several toggles in Toggle.Group with type="single". The group holds the selected value as a string and passes it down through React context; each child Toggle with a matching value reads its pressed state from that context instead of its own useState. Clicking an inactive toggle activates it and deactivates the previous one; clicking the active toggle clears the selection.

Use defaultValue for an uncontrolled group that manages itself, or pair value with onValueChange to control it from your own state. This is the right shape for any mutually exclusive choice rendered as buttons — alignment, a view mode switch, a single-pick filter. Because the same Toggle component detects the group context at render time, you reuse it unchanged inside or outside a group.

When several toggles should be independently on or off at once — the bold, italic, underline toolbar — use Toggle.Group with type="multiple". The group now holds its value as a string array, and each click adds or removes that toggle's value from the array. Every toggle reads whether its own value is in the array to decide its pressed state, so any combination can be active simultaneously.

This is the pattern for a rich-text formatting bar or any set of orthogonal options. Pass defaultValue={["bold", "italic"]} to start with several pressed, or control the array with value and onValueChange. The Toggle.Group accepts the same props in both modes — only type changes — so moving from single to multiple selection is a one-prop edit. Pair the result with a Button elsewhere in the toolbar for one-shot actions like "Clear formatting".

The toggle ships three sizes — sm, md, and lg — set with the size prop, mapping to heights of h-8, h-9, and h-10 with matching horizontal padding in the styles.sizes object. The default is md. Alongside size, the variant prop switches between the default look — a transparent button that fills with bg-muted when pressed — and outline, which adds a border that adjusts on press, useful when toggles sit on a busy surface and need a visible resting edge.

Both props are typed against the styles object, so size and variant autocomplete to the exact allowed values with no magic strings. Mixing them is free: an outline toggle at size="lg" is just two props. Because the classes live in your installed Toggle file, you can retune any size or variant by editing the object directly rather than reaching for a config layer.

Pass disabled to a single Toggle to drop it to 50% opacity and block clicks, or set disabled on a Toggle.Group to disable every toggle inside it — the group passes its disabled state down through context, and each child falls back to it when it has no disabled prop of its own. This is the clean way to grey out a whole formatting bar while a document is read-only.

For layout, Toggle.Group takes an orientation="vertical" prop that adds flex-col to stack the toggles in a column instead of a row — handy for a sidebar tool rail. Orientation is purely visual; selection behaviour is identical to a horizontal group. These two props compose with everything above, so a disabled, vertical, single-selection group is just three props on the group plus the toggles inside it.