Forms & Inputs
Toggle Group
A row of buttons that press and release, any number at once or one at a time, such as text styles or the filters on a list.
The toggle group is a row of buttons that stay pressed until they are pressed again: the
Bold, Italic and Underline of an editor, or the kinds of cover a list is filtered by. Any
number can be pressed at once, or, with type="single", one at a time. For one choice
that is always made and submitted with a form, such as a payment plan, use a
radio group of radio buttons;
for a single on/off button, a toggle button.
Preview
Section titled “Preview”Showing motor by month
<div style="display: grid; gap: 1rem">
<div style="display: grid; gap: 0.5rem">
<span style="font-size: 0.875rem; font-weight: 500">Cover</span>
<nana-toggle-group id="cover-demo" label="Cover" value="motor">
<nana-toggle-group-item value="motor">Motor</nana-toggle-group-item>
<nana-toggle-group-item value="health">Health</nana-toggle-group-item>
<nana-toggle-group-item value="life">Life</nana-toggle-group-item>
<nana-toggle-group-item value="travel" disabled>
Travel
</nana-toggle-group-item>
</nana-toggle-group>
</div>
<div style="display: grid; gap: 0.5rem">
<span style="font-size: 0.875rem; font-weight: 500">Period</span>
<nana-toggle-group
id="period-demo"
label="Period"
type="single"
required
size="sm"
value="month"
>
<nana-toggle-group-item value="week">Week</nana-toggle-group-item>
<nana-toggle-group-item value="month">Month</nana-toggle-group-item>
<nana-toggle-group-item value="year">Year</nana-toggle-group-item>
</nana-toggle-group>
</div>
<p
id="toggle-shown"
style="
margin: 0;
font-size: 0.875rem;
color: var(--nana-surface-text-muted);
"
>
Showing motor by month
</p>
</div>
<script type="module">
const cover = document.getElementById("cover-demo");
const period = document.getElementById("period-demo");
const show = () => {
document.getElementById("toggle-shown").textContent =
"Showing " +
(cover.value.join(", ") || "no cover") +
" by " +
period.value[0];
};
cover.addEventListener("nana-change", show);
period.addEventListener("nana-change", show);
</script> Showing motor by month
<script lang="ts">
import { NanaToggleGroup, NanaToggleGroupItem } from '$lib';
let cover = $state(['motor']);
let period = $state(['month']);
</script>
<div class="grid gap-4">
<div class="grid gap-2">
<span class="text-sm font-medium text-foreground">Cover</span>
<NanaToggleGroup bind:value={cover} label="Cover">
<NanaToggleGroupItem value="motor">Motor</NanaToggleGroupItem>
<NanaToggleGroupItem value="health">Health</NanaToggleGroupItem>
<NanaToggleGroupItem value="life">Life</NanaToggleGroupItem>
<NanaToggleGroupItem value="travel" disabled>Travel</NanaToggleGroupItem>
</NanaToggleGroup>
</div>
<div class="grid gap-2">
<span class="text-sm font-medium text-foreground">Period</span>
<NanaToggleGroup bind:value={period} type="single" required label="Period" size="sm">
<NanaToggleGroupItem value="week">Week</NanaToggleGroupItem>
<NanaToggleGroupItem value="month">Month</NanaToggleGroupItem>
<NanaToggleGroupItem value="year">Year</NanaToggleGroupItem>
</NanaToggleGroup>
</div>
<p class="text-sm text-foreground-muted">
Showing {cover.join(', ') || 'no cover'} by {period[0]}
</p>
</div> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add toggle-group --framework web-componentsnpx @nana-tec/ui add toggle-group --framework svelteLands in src/lib/components/ui/toggle-group/ as NanaToggleGroup.svelte and
NanaToggleGroupItem.svelte, styled with Tailwind classes that resolve to the design
tokens. Requires Tailwind v4.
<script lang="ts"> import { NanaToggleGroup, NanaToggleGroupItem } from '$lib/components/ui/toggle-group';
let styles = $state<string[]>([]);</script>
<NanaToggleGroup bind:value={styles} label="Text style"> <NanaToggleGroupItem value="bold">Bold</NanaToggleGroupItem> <NanaToggleGroupItem value="italic">Italic</NanaToggleGroupItem> <NanaToggleGroupItem value="underline">Underline</NanaToggleGroupItem></NanaToggleGroup>value is bindable and is always a list, in the items’ order, even in a single group,
where it holds one value or none. onValueChange receives it too.
Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and
each component downloads only the first time a page uses it:
import "@nana-tec/ui-components/autoloader";import "@nana-tec/ui-components/theme";The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.
Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:
import "@nana-tec/ui-components/toggle-group";
Copied in with npx @nana-tec/ui add toggle-group? Import your project's own
@/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.
<nana-toggle-group label="Text style" value="bold"> <nana-toggle-group-item value="bold">Bold</nana-toggle-group-item> <nana-toggle-group-item value="italic">Italic</nana-toggle-group-item> <nana-toggle-group-item value="underline">Underline</nana-toggle-group-item></nana-toggle-group>
<script type="module"> document.querySelector('nana-toggle-group').addEventListener('nana-change', (event) => { console.log(event.detail.value); });</script>value is a list, in the items’ order, even in a single group, where it holds one value
or none. As an attribute it is space-separated: value="bold italic". nana-change
reports each new list.
One at a time
Section titled “One at a time”With type="single", pressing an item releases the one before it, and pressing the
pressed item releases it, leaving none. Add required to keep one pressed always, as in
the Period group above. required in a multiple group keeps the last item from being
released.
In a single group the pressed fill flows from the old item to the new one, as the tabs’ thumb does; with reduced motion it moves at once. Every item presses in slightly when it is clicked or tapped.
An item can show only an icon. Give it an aria-label, since the icon names nothing:
<NanaToggleGroupItem value="bold" aria-label="Bold"><BoldIcon /></NanaToggleGroupItem><nana-toggle-group-item value="bold" aria-label="Bold"> <nana-icon name="bold"></nana-icon></nana-toggle-group-item>Layout
Section titled “Layout”size is sm, md or lg. orientation="vertical" stacks the items, for a toolbar down
the side of a canvas. disabled on the group disables every item; on an item, that one.
Keyboard
Section titled “Keyboard”| Key | Does |
|---|---|
| Tab | Moves into the group, onto the last item focused, the first pressed, or the first |
| Left and Right arrows | Move between items, wrapping, skipping disabled ones (Up and Down when vertical) |
| Home and End | Go to the first or last item |
| Space or Enter | Presses or releases the item |
Accessibility
Section titled “Accessibility”- The group is a
groupnamed bylabel; name it after what the items choose, such as “Cover”. - Each item is a button announced as pressed or not pressed.
- The whole group is one stop in the tab order, so a long row does not make keyboard users press Tab once per item.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Blocks interaction and leaves the value out of form submission. |
label | label | string | '' | Names the group for screen readers |
orientation | orientation | ToggleGroupOrientation | 'horizontal' | Lays the items out in a row (horizontal) or a column (vertical). |
required | required | boolean | false | Keep at least one item pressed |
size | size | 'sm' | 'md' | 'lg' | 'md' | Size preset. |
type | type | ToggleGroupType | 'multiple' | multiple lets any number be pressed; single one at a time |
value | value | string[] | [] | The pressed items' values, in item order; a space-separated list as an attribute |
Events
| Event | Description |
|---|---|
nana-change | When an item is pressed or released (detail.value, a list) |
Slots
| Slot | Description |
|---|---|
(default) | nana-toggle-group-item children |
CSS parts
| Part | Description |
|---|---|
::part(group) | The row around the items |
::part(thumb) | The pressed item's fill in a single group, which flows from item to item |
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
ariaLabel | aria-label | string | null | null | Names an item showing only an icon |
disabled | disabled | boolean | false | Blocks interaction and leaves the value out of form submission. |
groupDisabled | — | boolean | false | Set by the group: whether the whole group is disabled |
pressed | pressed | boolean | false | Set by the group |
size | size | 'sm' | 'md' | 'lg' | 'md' | Set by the group |
tabStop | — | boolean | true | Set by the group: whether Tab lands on this item |
value | value | string | '' | What the item adds to the group's value |
Slots
| Slot | Description |
|---|---|
(default) | The label, an icon, or both |
CSS parts
| Part | Description |
|---|---|
::part(item) | The button, with pressed while it is pressed |
CSS custom properties
| Property | Description |
|---|---|
--nana-toggle-group-item-height | Height and narrowest width of the button |
NanaToggleGroup
| Prop | Type | Default |
|---|---|---|
type | ToggleGroupType | 'multiple' |
valuebind: | string[] | [] |
label | string | |
orientation | ToggleGroupOrientation | 'horizontal' |
size | ToggleGroupSize | 'md' |
disabled | boolean | false |
required | boolean | false |
onValueChange | (value: string[]) => void | |
children | Snippet |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.
NanaToggleGroupItem
| Prop | Type | Default |
|---|---|---|
valuerequired | string | |
disabled | boolean | false |
children | Snippet |
Also accepts Omit<HTMLButtonAttributes, 'class' | 'value' | 'type'>.