Skip to content
WebJs
Menu

Toggle Group

A set of two-state buttons that can be toggled on or off.

import { html } from '@webjsdev/core';
import { Bold, Italic, Underline } from '#lib/ui/lucide.ts';

export default function ToggleGroupDemo() {
  return html`
    <ui-toggle-group variant="outline" type="multiple">
      <ui-toggle-group-item value="bold" aria-label="Toggle bold">
        ${Bold()}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="italic" aria-label="Toggle italic">
        ${Italic()}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="strikethrough" aria-label="Toggle strikethrough">
        ${Underline()}
      </ui-toggle-group-item>
    </ui-toggle-group>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add toggle-group

Usage

import '#components/ui/toggle-group.ts';
<ui-toggle-group type="single">
  <ui-toggle-group-item value="a">A</ui-toggle-group-item>
  <ui-toggle-group-item value="b">B</ui-toggle-group-item>
  <ui-toggle-group-item value="c">C</ui-toggle-group-item>
</ui-toggle-group>

Composition

Use the following composition to build a <ui-toggle-group>:

ui-toggle-group
├── ui-toggle-group-item
└── ui-toggle-group-item

Outline

Use variant="outline" for an outline style.

All Missed
import { html } from '@webjsdev/core';

export default function ToggleGroupOutline() {
  return html`
    <ui-toggle-group variant="outline" type="single" value="all">
      <ui-toggle-group-item value="all" aria-label="Toggle all">
        All
      </ui-toggle-group-item>
      <ui-toggle-group-item value="missed" aria-label="Toggle missed">
        Missed
      </ui-toggle-group-item>
    </ui-toggle-group>
  `;
}
View Code

Size

Use the size attribute to change the size of the toggle group.

Top Bottom Left Right
Top Bottom Left Right
import { html } from '@webjsdev/core';

export default function ToggleGroupSizes() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-toggle-group type="single" size="sm" value="top" variant="outline">
        <ui-toggle-group-item value="top" aria-label="Toggle top">
          Top
        </ui-toggle-group-item>
        <ui-toggle-group-item value="bottom" aria-label="Toggle bottom">
          Bottom
        </ui-toggle-group-item>
        <ui-toggle-group-item value="left" aria-label="Toggle left">
          Left
        </ui-toggle-group-item>
        <ui-toggle-group-item value="right" aria-label="Toggle right">
          Right
        </ui-toggle-group-item>
      </ui-toggle-group>
      <ui-toggle-group type="single" value="top" variant="outline">
        <ui-toggle-group-item value="top" aria-label="Toggle top">
          Top
        </ui-toggle-group-item>
        <ui-toggle-group-item value="bottom" aria-label="Toggle bottom">
          Bottom
        </ui-toggle-group-item>
        <ui-toggle-group-item value="left" aria-label="Toggle left">
          Left
        </ui-toggle-group-item>
        <ui-toggle-group-item value="right" aria-label="Toggle right">
          Right
        </ui-toggle-group-item>
      </ui-toggle-group>
    </div>
  `;
}
View Code

Spacing

Use spacing to add spacing between toggle group items. In the kit any value other than "0" separates the items with the same gap.

Top Bottom Left Right
import { html } from '@webjsdev/core';

export default function ToggleGroupSpacing() {
  return html`
    <ui-toggle-group type="single" size="sm" value="top" variant="outline" spacing="2">
      <ui-toggle-group-item value="top" aria-label="Toggle top">
        Top
      </ui-toggle-group-item>
      <ui-toggle-group-item value="bottom" aria-label="Toggle bottom">
        Bottom
      </ui-toggle-group-item>
      <ui-toggle-group-item value="left" aria-label="Toggle left">
        Left
      </ui-toggle-group-item>
      <ui-toggle-group-item value="right" aria-label="Toggle right">
        Right
      </ui-toggle-group-item>
    </ui-toggle-group>
  `;
}
View Code

Vertical

Use orientation="vertical" for vertical toggle groups.

import { html } from '@webjsdev/core';
import { BoldIcon, ItalicIcon, UnderlineIcon } from '#lib/ui/lucide.ts';

export default function ToggleGroupVertical() {
  return html`
    <ui-toggle-group type="multiple" orientation="vertical" spacing="1" value="bold,italic">
      <ui-toggle-group-item value="bold" aria-label="Toggle bold">
        ${BoldIcon()}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="italic" aria-label="Toggle italic">
        ${ItalicIcon()}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="underline" aria-label="Toggle underline">
        ${UnderlineIcon()}
      </ui-toggle-group-item>
    </ui-toggle-group>
  `;
}
View Code

Disabled

To disable items, put disabled on each item: a disabled item refuses clicks and is skipped by the arrow keys.

import { html } from '@webjsdev/core';
import { Bold, Italic, Underline } from '#lib/ui/lucide.ts';

// The group has no disabled attribute of its own, so each item carries one.
export default function ToggleGroupDisabled() {
  return html`
    <ui-toggle-group type="multiple">
      <ui-toggle-group-item value="bold" aria-label="Toggle bold" disabled>
        ${Bold()}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="italic" aria-label="Toggle italic" disabled>
        ${Italic()}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="strikethrough" aria-label="Toggle strikethrough" disabled>
        ${Underline()}
      </ui-toggle-group-item>
    </ui-toggle-group>
  `;
}
View Code

Custom

A custom toggle group example.

Aa Light Aa Normal Aa Medium Aa Bold

Use font-normal to set the font weight.

import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';

const weights = [
  { value: 'light', label: 'Light', class: 'font-light' },
  { value: 'normal', label: 'Normal', class: 'font-normal' },
  { value: 'medium', label: 'Medium', class: 'font-medium' },
  { value: 'bold', label: 'Bold', class: 'font-bold' },
];

// The group shows its initial selection, "normal". Picking another weight
// updates the group's value and dispatches ui-value-change.
export default function ToggleGroupFontWeightSelector() {
  const fontWeight = 'normal';
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" class=${fieldLabelClass()}>Font Weight</label>
      <ui-toggle-group type="single" value=${fontWeight} variant="outline" spacing="2" size="lg">
        ${weights.map((w) => html`
          <ui-toggle-group-item value=${w.value} aria-label=${w.label} class="flex size-16 flex-col items-center justify-center rounded-xl">
            <span class=${'text-2xl leading-none ' + w.class}>Aa</span>
            <span class="text-xs text-muted-foreground">${w.label}</span>
          </ui-toggle-group-item>
        `)}
      </ui-toggle-group>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>
        Use
        <code class="rounded-md bg-muted px-1 py-0.5 font-mono">font-${fontWeight}</code>
        to set the font weight.
      </p>
    </div>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

قائمة شبكة بطاقات
import { html } from '@webjsdev/core';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      list: 'List',
      grid: 'Grid',
      cards: 'Cards',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      list: 'قائمة',
      grid: 'شبكة',
      cards: 'بطاقات',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      list: 'רשימה',
      grid: 'רשת',
      cards: 'כרטיסים',
    },
  },
};

// The provider is the dir attribute: the group styles itself with logical
// properties, so dir="rtl" on it flips the item order.
export default function ToggleGroupRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <ui-toggle-group variant="outline" type="single" value="list" dir=${dir} lang=${lang}>
      <ui-toggle-group-item value="list" aria-label=${t.list}>
        ${t.list}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="grid" aria-label=${t.grid}>
        ${t.grid}
      </ui-toggle-group-item>
      <ui-toggle-group-item value="cards" aria-label=${t.cards}>
        ${t.cards}
      </ui-toggle-group-item>
    </ui-toggle-group>
  `;
}
View Code

API Reference

ui-toggle-group

The group. It owns the selection and reflects it onto its items, and it is a single Tab stop: the arrow keys move between items, Home and End jump to the first and last.

AttributeTypeDefault
type"single" | "multiple""single"
valuestring, comma separated when type="multiple"""
variant"default" | "outline""default"
size"default" | "sm" | "lg""default"
spacingstring, "0" for joined items"0"
orientation"horizontal" | "vertical""horizontal"

It dispatches ui-value-change with { detail: { value } } after the selection changes.

ui-toggle-group-item

One item, styled like a Toggle. An icon-only item needs an aria-label.

AttributeTypeDefault
valuestring""
pressedboolean, set by the groupfalse
disabledbooleanfalse

Changelog

2026-05-17 Default Spacing

The default spacing is now 2, so toggle groups render with space between items. With spacing left out the style decides: every style but new-york gaps the items by 2 spacing units, and new-york joins them. Set spacing="0" to join the items in any style.