Actions

Toggle

A button that turns an option on or off.

Class name	Type	Description
`btnplf:btn`	Component	A Button with data-plf-toggle
`btn-iconplf:btn-icon`	Part	An SVG icon in the toggle; an icon class there doesn't need it
`btn-ghostplf:btn-ghost`	Style	No border until pressed
`btn-outlineplf:btn-outline`	Style	Outline on the surface
`btn-smplf:btn-sm`	Size	Small
`btn-lgplf:btn-lg`	Size	Large
`btn-squareplf:btn-square`	Modifier	Square, for an icon-only toggle

Default

<button class="btn btn-ghost" data-plf-toggle>Toggle</button>
<button class="btn btn-ghost" data-plf-toggle aria-pressed="true">Pressed toggle</button>

<button class="plf:btn plf:btn-ghost" data-plf-toggle>Toggle</button>
<button class="plf:btn plf:btn-ghost" data-plf-toggle aria-pressed="true">Pressed toggle</button>

import { Toggle } from '@pelatform/react';

export function Example() {
  return (
    <>
      <Toggle>Toggle</Toggle>
      <Toggle defaultPressed>Pressed toggle</Toggle>
    </>
  );
}

import { Toggle } from '@pelatform/react/prefixed';

export function Example() {
  return (
    <>
      <Toggle>Toggle</Toggle>
      <Toggle defaultPressed>Pressed toggle</Toggle>
    </>
  );
}

aria-pressed tells assistive technologies the state, so keep the same label in both states.

Outline

<button class="btn btn-outline" data-plf-toggle>Toggle</button>
<button class="btn btn-outline" data-plf-toggle aria-pressed="true">Pressed toggle</button>

<button class="plf:btn plf:btn-outline" data-plf-toggle>Toggle</button>
<button class="plf:btn plf:btn-outline" data-plf-toggle aria-pressed="true">Pressed toggle</button>

import { Toggle } from '@pelatform/react';

export function Example() {
  return (
    <>
      <Toggle variant="outline">Toggle</Toggle>
      <Toggle variant="outline" defaultPressed>Pressed toggle</Toggle>
    </>
  );
}

import { Toggle } from '@pelatform/react/prefixed';

export function Example() {
  return (
    <>
      <Toggle variant="outline">Toggle</Toggle>
      <Toggle variant="outline" defaultPressed>Pressed toggle</Toggle>
    </>
  );
}

With icons

An icon-only toggle needs an aria-label.

<button class="btn btn-ghost" data-plf-toggle>
  <span class="icon icon-bookmark"></span>
  Bookmark
</button>
<button class="btn btn-outline btn-square" data-plf-toggle aria-pressed="true" aria-label="Bold">
  <span class="icon icon-bold"></span>
</button>
<button class="btn btn-outline btn-square" data-plf-toggle aria-label="Italic">
  <span class="icon icon-italic"></span>
</button>
<button class="btn btn-outline btn-square" data-plf-toggle aria-label="Underline">
  <span class="icon icon-underline"></span>
</button>

<button class="plf:btn plf:btn-ghost" data-plf-toggle>
  <span class="plf:icon plf:icon-bookmark"></span>
  Bookmark
</button>
<button class="plf:btn plf:btn-outline plf:btn-square" data-plf-toggle aria-pressed="true" aria-label="Bold">
  <span class="plf:icon plf:icon-bold"></span>
</button>
<button class="plf:btn plf:btn-outline plf:btn-square" data-plf-toggle aria-label="Italic">
  <span class="plf:icon plf:icon-italic"></span>
</button>
<button class="plf:btn plf:btn-outline plf:btn-square" data-plf-toggle aria-label="Underline">
  <span class="plf:icon plf:icon-underline"></span>
</button>

import { Icon, Toggle } from '@pelatform/react';

export function Example() {
  return (
    <>
      <Toggle>
        <Icon name="bookmark" />
        Bookmark
      </Toggle>
      <Toggle variant="outline" shape="square" defaultPressed aria-label="Bold">
        <Icon name="bold" />
      </Toggle>
      <Toggle variant="outline" shape="square" aria-label="Italic">
        <Icon name="italic" />
      </Toggle>
      <Toggle variant="outline" shape="square" aria-label="Underline">
        <Icon name="underline" />
      </Toggle>
    </>
  );
}

import { Icon, Toggle } from '@pelatform/react/prefixed';

export function Example() {
  return (
    <>
      <Toggle>
        <Icon name="bookmark" />
        Bookmark
      </Toggle>
      <Toggle variant="outline" shape="square" defaultPressed aria-label="Bold">
        <Icon name="bold" />
      </Toggle>
      <Toggle variant="outline" shape="square" aria-label="Italic">
        <Icon name="italic" />
      </Toggle>
      <Toggle variant="outline" shape="square" aria-label="Underline">
        <Icon name="underline" />
      </Toggle>
    </>
  );
}

Sizes

<button class="btn btn-outline btn-sm" data-plf-toggle>Small</button>
<button class="btn btn-outline" data-plf-toggle>Default</button>
<button class="btn btn-outline btn-lg" data-plf-toggle>Large</button>

<button class="plf:btn plf:btn-outline plf:btn-sm" data-plf-toggle>Small</button>
<button class="plf:btn plf:btn-outline" data-plf-toggle>Default</button>
<button class="plf:btn plf:btn-outline plf:btn-lg" data-plf-toggle>Large</button>

import { Toggle } from '@pelatform/react';

export function Example() {
  return (
    <>
      <Toggle variant="outline" size="sm">Small</Toggle>
      <Toggle variant="outline">Default</Toggle>
      <Toggle variant="outline" size="lg">Large</Toggle>
    </>
  );
}

import { Toggle } from '@pelatform/react/prefixed';

export function Example() {
  return (
    <>
      <Toggle variant="outline" size="sm">Small</Toggle>
      <Toggle variant="outline">Default</Toggle>
      <Toggle variant="outline" size="lg">Large</Toggle>
    </>
  );
}

Disabled

<button class="btn btn-outline" data-plf-toggle disabled>Toggle</button>
<button class="btn btn-outline" data-plf-toggle aria-pressed="true" disabled>Pressed toggle</button>

<button class="plf:btn plf:btn-outline" data-plf-toggle disabled>Toggle</button>
<button class="plf:btn plf:btn-outline" data-plf-toggle aria-pressed="true" disabled>Pressed toggle</button>

import { Toggle } from '@pelatform/react';

export function Example() {
  return (
    <>
      <Toggle variant="outline" disabled>Toggle</Toggle>
      <Toggle variant="outline" defaultPressed disabled>Pressed toggle</Toggle>
    </>
  );
}

import { Toggle } from '@pelatform/react/prefixed';

export function Example() {
  return (
    <>
      <Toggle variant="outline" disabled>Toggle</Toggle>
      <Toggle variant="outline" defaultPressed disabled>Pressed toggle</Toggle>
    </>
  );
}

Toggle needs JavaScript to change its state. The Full script (pelatform-ui.min.js) starts every component on page load, with no code of your own; with ESM imports, call init() yourself, as in Installation. For markup you add later, see Dynamic content.

<link rel="stylesheet" href="pelatform-ui.min.css">
<link rel="stylesheet" href="icons/icons.min.css">
<script src="pelatform-ui.min.js" defer></script>

<link rel="stylesheet" href="core/pelatform-ui-core.min.css">
<link rel="stylesheet" href="components/button.min.css">
<link rel="stylesheet" href="components/toggle.min.css">
<link rel="stylesheet" href="icons/icons.min.css">
<script src="core/pelatform-ui-core.min.js" defer></script>
<script src="components/toggle.min.js" defer></script>
<script>document.addEventListener('DOMContentLoaded', () => PLF.init());</script>

<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<link rel="stylesheet" href="icons/icons.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>

<link rel="stylesheet" href="core/pelatform-ui-core.prefixed.min.css">
<link rel="stylesheet" href="components/button.prefixed.min.css">
<link rel="stylesheet" href="components/toggle.prefixed.min.css">
<link rel="stylesheet" href="icons/icons.prefixed.min.css">
<script src="core/pelatform-ui-core.min.js" defer></script>
<script src="components/toggle.min.js" defer></script>
<script>document.addEventListener('DOMContentLoaded', () => PLF.init());</script>

Hooks

Attribute	Purpose
`data-plf-toggle`	Marks a `<button>` as a toggle
`aria-pressed`	The state: `"true"` starts pressed; the script adds `"false"` when it is left out, and updates it on change
`disabled`	Blocks clicks and method calls

Methods

Method	Behavior
`PLF.Toggle.getOrCreateInstance(button)`	Returns the instance, creating it for valid markup
`PLF.Toggle.getInstance(button)`	Returns the instance or `null`
`instance.setPressed(pressed)`	Sets the state from a boolean; returns `false` when unchanged, canceled or disabled
`instance.toggle()`	Switches the state; returns like `setPressed`
`instance.destroy()`	Removes the listener; the state stays

Events

Event	When
`plf:toggle:before-change`	Before the state changes; cancelable
`plf:toggle:change`	After `aria-pressed` is updated

Each event’s detail:

Property	Value
`instance`	The Toggle instance
`reason`	`api` or `trigger`
`trigger`	The toggle, or `null` from a method
`previousPressed`	The state before: `true` when pressed
`pressed`	The new state: `true` when pressed

Toggle only changes its state: apply the effect, such as formatting, in your plf:toggle:change handler. It submits no form value.

Keyboard

Key	Action
Enter, Space	Toggles the focused button
Tab, Shift+Tab	Move between toggles

React

Toggle from @pelatform/react renders this button with aria-pressed, which a click switches; it keeps its own state, or the application sets it with pressed.

Prop	Values	Default
`variant`	`ghost`, `outline`	`ghost`
`size`	`sm`, `lg`	The default size
`shape`	`square`, for an icon-only toggle with an `aria-label`	None
`pressed`	`true` or `false`, which the application changes in `onPressedChange`	Its own state
`defaultPressed`	`true` starts pressed when the application does not set `pressed`	`false`
`onPressedChange`	`(pressed)`, called when a click presses or releases the toggle	None

The other props are a native button’s, className and ref included. It is type="button", so it never submits a form, and inside a ButtonGroup the toggle is joined.

CSS variables

The pressed state reads these; everything else is Button’s.

Variable	Default
`--plf-toggle-pressed-bg`	`--plf-color-primary-subtle`
`--plf-toggle-pressed-color`	`--plf-color-primary-text`
`--plf-toggle-pressed-border`	`--plf-color-primary-border`