Toggle
toggleSwitches a single action or formatting option between pressed and unpressed states.
Usage
Basic usage
A single Toggle is a switchable pressed button, and defaultPressed is initially selected.
<>
<Toggle aria-label="bold"><Bold className="size-4" /></Toggle>
<Toggle defaultPressed aria-label="bold"><Bold className="size-4" /></Toggle>
</>Single choice group
ToggleGroup Default mutually exclusive radio selection, suitable for switching such as alignment.
<ToggleGroup defaultValue={["center"]}>
<Toggle value="left" aria-label="Left justified"><AlignLeft className="size-4" /></Toggle>
<Toggle value="center" aria-label="center"><AlignCenter className="size-4" /></Toggle>
<Toggle value="right" aria-label="right-justified"><AlignRight className="size-4" /></Toggle>
</ToggleGroup>Multiple choice group
Add multiple to allow multiple items in the group to be pressed at the same time, suitable for rich text styles.
<ToggleGroup multiple defaultValue={["bold", "italic"]}>
<Toggle value="bold" aria-label="bold"><Bold className="size-4" /></Toggle>
<Toggle value="italic" aria-label="italic"><Italic className="size-4" /></Toggle>
<Toggle value="underline" aria-label="underline"><Underline className="size-4" /></Toggle>
</ToggleGroup>Variants
default soft bottom / outline main color solid / pill rounded corners chip (AI toolbar switch style).
<>
<Toggle defaultPressed aria-label="default"><Bold className="size-4" /></Toggle>
<Toggle variant="outline" defaultPressed aria-label="outline"><Bold className="size-4" /></Toggle>
<Toggle variant="pill" size="sm" defaultPressed aria-label="Deep Thought">
<Sparkles className="size-3.5" /> Deep Thoughts
</Toggle>
</>Disabled
disabled Lock button, which can also be disabled when pressed.
<Toggle disabled defaultPressed aria-label="bold"><Bold className="size-4" /></Toggle>When to use
Use Toggle for an icon or text button with a persistent pressed state, such as Bold, alignment, or an AI toolbar mode. ToggleGroup coordinates mutually exclusive or multiple pressed items. Use Switch for an immediately applied setting, or Radio for a conventional group of equivalent form choices.
Import
import { Toggle, ToggleGroup, toggleVariants } from "@hulianui/ui"Props
Toggle
| Name | Type | Default | Description |
|---|---|---|---|
| pressed | boolean | — | controlled pressed state |
| defaultPressed | boolean | false | Uncontrolled initial press state |
| disabled | boolean | false | Disable |
| value | string | — | Identifies the item within the ToggleGroup |
| variant | "default"|"outline"|"pill" | "default" | default=grey background soft selection / outline=main color solid / pill=rounded stroke + soft main color selection (AI toolbar switch style) |
| size | "sm"|"md" | "md" | — |
| className | string | — | — |
| aria-label | string | — | Required if only icon |
ToggleGroup
| Name | Type | Default | Description |
|---|---|---|---|
| value | string[] | — | Controlled: item value array has been pressed |
| defaultValue | string[] | — | Uncontrolled initial item-by-item array |
| disabled | boolean | false | Disable entire group |
| multiple | boolean | false | true=multiple selections coexist; false=single selections are mutually exclusive |
| orientation | "horizontal"|"vertical" | "horizontal" | — |
| className | string | — | — |
Events
Toggle
| Event | Type | Description |
|---|---|---|
| onPressedChange | (pressed: boolean) => void | Pressed state change (Hulian converges signature, loses Base UI eventDetails) |
ToggleGroup
| Event | Type | Description |
|---|---|---|
| onValueChange | (value: string[]) => void | change callback |
Slots
Toggle
| Slot | Type | Description |
|---|---|---|
| children | ReactNode | icon / text |
ToggleGroup
| Slot | Type | Description |
|---|---|---|
| children | ReactNode | Item Toggle is included |
Example
Single toggle (controlled):
const [on, setOn] = useState(false);
<Toggle pressed={on} onPressedChange={setOn} aria-label="Bold">
<Bold className="size-4" />
</Toggle>Mutually exclusive radio group:
<ToggleGroup defaultValue={["center"]}>
<Toggle value="left" aria-label="Align left"><AlignLeft className="size-4" /></Toggle>
<Toggle value="center" aria-label="Align center"><AlignCenter className="size-4" /></Toggle>
<Toggle value="right" aria-label="Align right"><AlignRight className="size-4" /></Toggle>
</ToggleGroup>Usage guidelines
- ToggleGroup always represents pressed items as a value array; with
multiple={false}, the array contains zero or one value. - An icon-only Toggle needs
aria-labelso screen readers can identify the action. - Controlled usage requires
pressed/onPressedChange, or groupvalue/onValueChange. UsedefaultPressedordefaultValueonly when uncontrolled.
Related
Input · Textarea · Select · Checkbox · CheckboxGroup · Radio
Playground
<Toggle>
<Bold />
</Toggle>