Skip to content
WebJs
Menu

A two-state button that can be either on or off.

import { html } from '@webjsdev/core';
import { BookmarkIcon } from '#lib/ui/lucide.ts';

export default function ToggleDemo() {
  return html`
    <ui-toggle aria-label="Toggle bookmark" size="sm" variant="outline">
      ${BookmarkIcon('group-data-[state=on]/toggle:fill-foreground')}
      Bookmark
    </ui-toggle>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add toggle

Usage

Importing the module registers <ui-toggle>, which keeps its own pressed state.

import '#components/ui/toggle.ts';
<ui-toggle>Toggle</ui-toggle>

Outline

Use variant="outline" for an outline style.

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

export default function ToggleOutline() {
  return html`
    <div class="flex flex-wrap items-center gap-2">
      <ui-toggle variant="outline" aria-label="Toggle italic">
        ${ItalicIcon()}
        Italic
      </ui-toggle>
      <ui-toggle variant="outline" aria-label="Toggle bold">
        ${BoldIcon()}
        Bold
      </ui-toggle>
    </div>
  `;
}
View Code

With Text

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

export default function ToggleText() {
  return html`
    <ui-toggle aria-label="Toggle italic">
      ${ItalicIcon()}
      Italic
    </ui-toggle>
  `;
}
View Code

Size

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

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

export default function ToggleSizes() {
  return html`
    <div class="flex flex-wrap items-center gap-2">
      <ui-toggle variant="outline" aria-label="Toggle small" size="sm">
        Small
      </ui-toggle>
      <ui-toggle variant="outline" aria-label="Toggle default" size="default">
        Default
      </ui-toggle>
      <ui-toggle variant="outline" aria-label="Toggle large" size="lg">
        Large
      </ui-toggle>
    </div>
  `;
}
View Code

Disabled

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

export default function ToggleDisabled() {
  return html`
    <div class="flex flex-wrap items-center gap-2">
      <ui-toggle aria-label="Toggle disabled" disabled>
        Disabled
      </ui-toggle>
      <ui-toggle variant="outline" aria-label="Toggle disabled outline" disabled>
        Disabled
      </ui-toggle>
    </div>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

import { html } from '@webjsdev/core';
import { BookmarkIcon } from '#lib/ui/lucide.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      label: 'Bookmark',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      label: 'إشارة مرجعية',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      label: 'סימנייה',
    },
  },
};

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

  return html`
    <ui-toggle aria-label="Toggle bookmark" size="sm" variant="outline" dir=${dir} lang=${lang}>
      ${BookmarkIcon('group-data-[state=on]/toggle:fill-foreground')}
      ${t.label}
    </ui-toggle>
  `;
}
View Code

API Reference

ui-toggle

A pressable on and off button. It renders a native <button> and forwards the host's aria-label to it, so an icon-only toggle is named on the host.

AttributeTypeDefault
pressedbooleanfalse
variant"default" | "outline""default"
size"default" | "sm" | "lg""default"
disabledbooleanfalse

It dispatches ui-pressed-change with { detail: { pressed } } after a click.

toggleClass

toggleClass() returns the toggle's classes for a native <button> whose pressed state you own, carried on aria-pressed and data-state. toggleVariants() is an alias of toggleClass() that also merges a className.

OptionTypeDefault
variant"default" | "outline""default"
size"default" | "sm" | "lg""default"