Skip to content
Nana UI

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.

View .md Download

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.

Cover Motor Health Life Travel
Period Week Month Year

Showing motor by month

Cover
Period

Showing motor by month

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add toggle-group --framework web-components
npx @nana-tec/ui add toggle-group --framework svelte

Lands 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.

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>

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.

KeyDoes
TabMoves into the group, onto the last item focused, the first pressed, or the first
Left and Right arrowsMove between items, wrapping, skipping disabled ones (Up and Down when vertical)
Home and EndGo to the first or last item
Space or EnterPresses or releases the item
  • The group is a group named by label; 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

PropertyAttributeTypeDefaultDescription
disableddisabledbooleanfalseBlocks interaction and leaves the value out of form submission.
labellabelstring''Names the group for screen readers
orientationorientationToggleGroupOrientation'horizontal'Lays the items out in a row (horizontal) or a column (vertical).
requiredrequiredbooleanfalseKeep at least one item pressed
sizesize'sm' | 'md' | 'lg''md'Size preset.
typetypeToggleGroupType'multiple'multiple lets any number be pressed; single one at a time
valuevaluestring[][]The pressed items' values, in item order; a space-separated list as an attribute

Events

EventDescription
nana-changeWhen an item is pressed or released (detail.value, a list)

Slots

SlotDescription
(default)nana-toggle-group-item children

CSS parts

PartDescription
::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

PropertyAttributeTypeDefaultDescription
ariaLabelaria-labelstring | nullnullNames an item showing only an icon
disableddisabledbooleanfalseBlocks interaction and leaves the value out of form submission.
groupDisabled—booleanfalseSet by the group: whether the whole group is disabled
pressedpressedbooleanfalseSet by the group
sizesize'sm' | 'md' | 'lg''md'Set by the group
tabStop—booleantrueSet by the group: whether Tab lands on this item
valuevaluestring''What the item adds to the group's value

Slots

SlotDescription
(default)The label, an icon, or both

CSS parts

PartDescription
::part(item)The button, with pressed while it is pressed

CSS custom properties

PropertyDescription
--nana-toggle-group-item-heightHeight and narrowest width of the button

NanaToggleGroup

PropTypeDefault
typeToggleGroupType'multiple'
valuebind:string[][]
labelstring
orientationToggleGroupOrientation'horizontal'
sizeToggleGroupSize'md'
disabledbooleanfalse
requiredbooleanfalse
onValueChange(value: string[]) => void
childrenSnippet

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.

NanaToggleGroupItem

PropTypeDefault
valuerequiredstring
disabledbooleanfalse
childrenSnippet

Also accepts Omit<HTMLButtonAttributes, 'class' | 'value' | 'type'>.