The Toggle component provides a switch interface that allows users to toggle between on and off states. It supports various sizes, animations, and customization options with full form integration.

Usage

Basic Example

A simple toggle switch.

Enable notifications

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle>
        Enable notifications
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle>
      Enable notifications
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle>
    Enable notifications
  </plus-toggle>
</template>

Svelte

<plus-toggle>
  Enable notifications
</plus-toggle>

HTML

<plus-toggle>
  Enable notifications
</plus-toggle>

With Label

Use the label prop to add a label above the toggle.

Dark mode

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle label="Settings">
        Dark mode
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle label="Settings">
      Dark mode
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle label="Settings">
    Dark mode
  </plus-toggle>
</template>

Svelte

<plus-toggle label="Settings">
  Dark mode
</plus-toggle>

HTML

<plus-toggle label="Settings">
  Dark mode
</plus-toggle>

Size

Control the toggle’s size using the size prop.

Toggle sizeToggle sizeToggle size

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle size="sm">
        Toggle size
      </PlusToggle>
      <PlusToggle size="md">
        Toggle size
      </PlusToggle>
      <PlusToggle size="lg">
        Toggle size
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle size="sm">
      Toggle size
    </plus-toggle>
    <plus-toggle size="md">
      Toggle size
    </plus-toggle>
    <plus-toggle size="lg">
      Toggle size
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle size="sm">
    Toggle size
  </plus-toggle>
  <plus-toggle size="md">
    Toggle size
  </plus-toggle>
  <plus-toggle size="lg">
    Toggle size
  </plus-toggle>
</template>

Svelte

<plus-toggle size="sm">
  Toggle size
</plus-toggle>
<plus-toggle size="md">
  Toggle size
</plus-toggle>
<plus-toggle size="lg">
  Toggle size
</plus-toggle>

HTML

<plus-toggle size="sm">
  Toggle size
</plus-toggle>
<plus-toggle size="md">
  Toggle size
</plus-toggle>
<plus-toggle size="lg">
  Toggle size
</plus-toggle>

Checked State

Set the initial state using the checked prop.

Toggle stateToggle state

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle checked="false">
        Toggle state
      </PlusToggle>
      <PlusToggle checked="true">
        Toggle state
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle checked="false">
      Toggle state
    </plus-toggle>
    <plus-toggle checked="true">
      Toggle state
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle checked="false">
    Toggle state
  </plus-toggle>
  <plus-toggle checked="true">
    Toggle state
  </plus-toggle>
</template>

Svelte

<plus-toggle checked="false">
  Toggle state
</plus-toggle>
<plus-toggle checked="true">
  Toggle state
</plus-toggle>

HTML

<plus-toggle checked="false">
  Toggle state
</plus-toggle>
<plus-toggle checked="true">
  Toggle state
</plus-toggle>

Text Position

Control the text position using the text-position prop.

Toggle text position

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle data-variant-textPosition="left,right">
        Toggle text position
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle data-variant-text-position="left,right">
      Toggle text position
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle data-variant-text-position="left,right">
    Toggle text position
  </plus-toggle>
</template>

Svelte

<plus-toggle data-variant-text-position="left,right">
  Toggle text position
</plus-toggle>

HTML

<plus-toggle data-variant-text-position="left,right">
  Toggle text position
</plus-toggle>

Animation Types

Choose from different animation styles.

Animation styleAnimation styleAnimation style

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle animation="default">
        Animation style
      </PlusToggle>
      <PlusToggle animation="bounce">
        Animation style
      </PlusToggle>
      <PlusToggle animation="smooth">
        Animation style
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle animation="default">
      Animation style
    </plus-toggle>
    <plus-toggle animation="bounce">
      Animation style
    </plus-toggle>
    <plus-toggle animation="smooth">
      Animation style
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle animation="default">
    Animation style
  </plus-toggle>
  <plus-toggle animation="bounce">
    Animation style
  </plus-toggle>
  <plus-toggle animation="smooth">
    Animation style
  </plus-toggle>
</template>

Svelte

<plus-toggle animation="default">
  Animation style
</plus-toggle>
<plus-toggle animation="bounce">
  Animation style
</plus-toggle>
<plus-toggle animation="smooth">
  Animation style
</plus-toggle>

HTML

<plus-toggle animation="default">
  Animation style
</plus-toggle>
<plus-toggle animation="bounce">
  Animation style
</plus-toggle>
<plus-toggle animation="smooth">
  Animation style
</plus-toggle>

With Icons

Add icons to the toggle using icon props.

Theme toggle

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle toggleIcon="sun" toggle-activeIcon="moon" toggle-inactiveIcon="sun">
        <p>
          Theme toggle
        </p>
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle toggle-icon="sun" toggle-active-icon="moon" toggle-inactive-icon="sun">
      <p>
        Theme toggle
      </p>
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle toggle-icon="sun" toggle-active-icon="moon" toggle-inactive-icon="sun">
    <p>
      Theme toggle
    </p>
  </plus-toggle>
</template>

Svelte

<plus-toggle toggle-icon="sun" toggle-active-icon="moon" toggle-inactive-icon="sun">
  <p>
    Theme toggle
  </p>
</plus-toggle>

HTML

<plus-toggle toggle-icon="sun" toggle-active-icon="moon" toggle-inactive-icon="sun">
  <p>
    Theme toggle
  </p>
</plus-toggle>

States

Toggle supports various states including disabled, readonly, and error.

Disabled stateDisabled state

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle disabled="false">
        Disabled state
      </PlusToggle>
      <PlusToggle disabled="true">
        Disabled state
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle disabled="false">
      Disabled state
    </plus-toggle>
    <plus-toggle disabled="true">
      Disabled state
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle disabled="false">
    Disabled state
  </plus-toggle>
  <plus-toggle disabled="true">
    Disabled state
  </plus-toggle>
</template>

Svelte

<plus-toggle disabled="false">
  Disabled state
</plus-toggle>
<plus-toggle disabled="true">
  Disabled state
</plus-toggle>

HTML

<plus-toggle disabled="false">
  Disabled state
</plus-toggle>
<plus-toggle disabled="true">
  Disabled state
</plus-toggle>

Readonly stateReadonly state

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle readonly="false">
        Readonly state
      </PlusToggle>
      <PlusToggle readonly="true">
        Readonly state
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle readonly="false">
      Readonly state
    </plus-toggle>
    <plus-toggle readonly="true">
      Readonly state
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle readonly="false">
    Readonly state
  </plus-toggle>
  <plus-toggle readonly="true">
    Readonly state
  </plus-toggle>
</template>

Svelte

<plus-toggle readonly="false">
  Readonly state
</plus-toggle>
<plus-toggle readonly="true">
  Readonly state
</plus-toggle>

HTML

<plus-toggle readonly="false">
  Readonly state
</plus-toggle>
<plus-toggle readonly="true">
  Readonly state
</plus-toggle>

Error stateError state

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle error="false" errorMessage="This field is required">
        Error state
      </PlusToggle>
      <PlusToggle error="true" errorMessage="This field is required">
        Error state
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle error="false" error-message="This field is required">
      Error state
    </plus-toggle>
    <plus-toggle error="true" error-message="This field is required">
      Error state
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle error="false" error-message="This field is required">
    Error state
  </plus-toggle>
  <plus-toggle error="true" error-message="This field is required">
    Error state
  </plus-toggle>
</template>

Svelte

<plus-toggle error="false" error-message="This field is required">
  Error state
</plus-toggle>
<plus-toggle error="true" error-message="This field is required">
  Error state
</plus-toggle>

HTML

<plus-toggle error="false" error-message="This field is required">
  Error state
</plus-toggle>
<plus-toggle error="true" error-message="This field is required">
  Error state
</plus-toggle>

With Caption

Add descriptive text below the toggle.

Enable notifications

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle caption="This will enable push notifications on your device">
        <p>
          Enable notifications
        </p>
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle caption="This will enable push notifications on your device">
      <p>
        Enable notifications
      </p>
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle caption="This will enable push notifications on your device">
    <p>
      Enable notifications
    </p>
  </plus-toggle>
</template>

Svelte

<plus-toggle caption="This will enable push notifications on your device">
  <p>
    Enable notifications
  </p>
</plus-toggle>

HTML

<plus-toggle caption="This will enable push notifications on your device">
  <p>
    Enable notifications
  </p>
</plus-toggle>

Full Width

Make the toggle take the full width of its container.

Full width toggle

Show code

React

import { PlusToggle } from '@plusui/react';

export default () => {
  return (
    <>
      <PlusToggle fullWidth="true">
        Full width toggle
      </PlusToggle>
    </>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <plus-toggle full-width="true">
      Full width toggle
    </plus-toggle>
  `
})
export class ExampleComponent {}

Vue

<template>
  <plus-toggle full-width="true">
    Full width toggle
  </plus-toggle>
</template>

Svelte

<plus-toggle full-width="true">
  Full width toggle
</plus-toggle>

HTML

<plus-toggle full-width="true">
  Full width toggle
</plus-toggle>

Form Integration

The toggle works seamlessly with forms and supports validation.

I accept the terms and conditions

Submit

Show code

React

import { PlusToggle } from '@plusui/react';
import { useState } from 'react';

export default () => {
  const [accepted, setAccepted] = useState(false);

  const handleSubmit = (e) => {
    e.preventDefault();
    console.log('Terms accepted:', accepted);
  };

  return (
    <form onSubmit={handleSubmit}>
      <PlusToggle
        name="terms"
        value="accepted"
        required
        checked={accepted}
        onPlusChange={(e) => setAccepted(e.target.checked)}
        errorMessage="You must accept the terms"
      >
        I accept the terms and conditions
      </PlusToggle>
      <br /><br />
      <button type="submit">Submit</button>
    </form>
  );
};

Angular

import { Component } from '@angular/core';

@Component({
  selector: 'app-toggle-form',
  template: `
    <form (ngSubmit)="handleSubmit()">
      <plus-toggle
        name="terms"
        value="accepted"
        required
        [checked]="accepted"
        (plus-change)="onToggleChange($event)"
        error-message="You must accept the terms"
      >
        I accept the terms and conditions
      </plus-toggle>
      <br /><br />
      <button type="submit">Submit</button>
    </form>
  `
})
export class ToggleFormComponent {
  accepted = false;

  onToggleChange(event: CustomEvent) {
    this.accepted = event.target.checked;
  }

  handleSubmit() {
    console.log('Terms accepted:', this.accepted);
  }
}

Vue

<template>
  <form @submit.prevent="handleSubmit">
    <plus-toggle
      name="terms"
      value="accepted"
      required
      :checked="accepted"
      @plus-change="onToggleChange"
      error-message="You must accept the terms"
    >
      I accept the terms and conditions
    </plus-toggle>
    <br /><br />
    <button type="submit">Submit</button>
  </form>
</template>

<script setup>
import { ref } from 'vue';

const accepted = ref(false);

const onToggleChange = (event) => {
  accepted.value = event.target.checked;
};

const handleSubmit = () => {
  console.log('Terms accepted:', accepted.value);
};
</script>

Svelte

<script>
  let accepted = false;

  const handleSubmit = (e) => {
    e.preventDefault();
    console.log('Terms accepted:', accepted);
  };

  const onToggleChange = (e) => {
    accepted = e.target.checked;
  };
</script>

<form on:submit={handleSubmit}>
  <plus-toggle
    name="terms"
    value="accepted"
    required
    checked={accepted}
    on:plus-change={onToggleChange}
    error-message="You must accept the terms"
  >
    I accept the terms and conditions
  </plus-toggle>
  <br /><br />
  <button type="submit">Submit</button>
</form>

HTML

<form id="toggle-form-html">
  <plus-toggle
    name="terms"
    value="accepted"
    required
    error-message="You must accept the terms"
  >
    I accept the terms and conditions
  </plus-toggle>
  <br /><br />
  <button type="submit">Submit</button>
</form>

<script>
  document.getElementById('toggle-form-html').addEventListener('submit', (e) => {
    e.preventDefault();
    const formData = new FormData(e.target);
    console.log('Form data:', Object.fromEntries(formData));
  });
</script>

Show console

Console Output:

No console output yet. Try interacting with the components above.

Clear Console

Accessibility (a11y)

• Screen Reader:
  • Uses role="switch" to identify the toggle as a switch control.
  • aria-checked indicates the current state (true/false).
  • aria-disabled indicates if the toggle is disabled.
  • aria-invalid indicates validation state.
  • aria-labelledby and aria-describedby provide proper labeling.
• Keyboard Navigation:
  • Space: Toggles the switch state.
  • Enter: Toggles the switch state.
  • Tab: Moves focus to/from the toggle.
• Required Developer Actions:
  • Provide meaningful labels or text content.
  • Use caption for additional context when needed.
  • Ensure sufficient color contrast for custom styling.

API Reference

Properties

Name	Type	Default	Description	Required
name	string	''	Name attribute for form submission.	No
value	string	'on'	Value submitted when toggle is checked.	No
checked	boolean	false	Whether the toggle is checked.	No
size	'sm' | 'md' | 'lg'	'md'	Size of the toggle.	No
label	string	undefined	Label text displayed above the toggle.	No
caption	string	undefined	Caption text displayed below the toggle.	No
text	string	undefined	Text content (can also be provided via slot).	No
textPosition	'left' | 'right'	'right'	Position of the text relative to the switch.	No
toggleIcon	string	undefined	Icon displayed in the toggle dot.	No
toggleActiveIcon	string	undefined	Icon displayed when toggle is active.	No
toggleInactiveIcon	string	undefined	Icon displayed when toggle is inactive.	No
error	boolean	false	Whether the toggle is in error state.	No
errorMessage	string	''	Error message displayed when in error state.	No
disabled	boolean	false	Whether the toggle is disabled.	No
readonly	boolean	false	Whether the toggle is readonly.	No
required	boolean	false	Whether the toggle is required for form validation.	No
fullWidth	boolean	false	Whether the toggle takes full width of its container.	No
animation	'default' | 'bounce' | 'smooth'	'default'	Animation style for the toggle transition.	No
customAriaLabel	string	undefined	Custom aria-label for accessibility.	No

Events

Name	Payload Type	Description
plus-change	CustomEvent<void>	Fired when the toggle state changes.
plus-input	CustomEvent<void>	Fired when the toggle state changes (input).
plus-focus	CustomEvent<void>	Fired when the toggle gains focus.
plus-blur	CustomEvent<void>	Fired when the toggle loses focus.
plus-invalid	CustomEvent<{message: string}>	Fired when validation fails.

Methods

Name	Parameters	Description
checkValidity()	None	Returns true if the toggle is valid.
reportValidity()	None	Reports validity and shows validation UI.
setCustomValidity()	message: string	Sets a custom validation message.
focus()	options?: FocusOptions	Focuses the toggle.
blur()	None	Removes focus from the toggle.
click()	None	Programmatically clicks the toggle.

Slots

Name	Description
default (unnamed)	The text content of the toggle.

CSS Shadow Parts

Part	Description
base	The main container element.
label	The label element.
control	The control element containing switch and text.
switch	The switch element.
dot	The dot element inside the switch.
text	The text element.
icon	The icon element in the dot.
caption	The caption element.

CSS Custom Properties

Name	Description
--text-color	Controls the text color.
--border-color	Controls the border color.
--switch-bg	Controls the switch background.
--switch-bg-hover	Controls the hover background.
--switch-bg-active	Controls the active background.
--dot-bg	Controls the dot background.
--dot-text	Controls the dot text/icon color.

Join the Community

Plus UI is built by the community. Join us on our platforms to contribute, get help, and stay up to date.

Figma GitHub Discord Twitter Open Collective