Skip to content

Toggle Icon

<quiet-toggle-icon> stable since 1.0

Toggle icons are like checkboxes, except with icons to represent the checked and unchecked states.

Toggle icons can be used just like checkboxes and switches to turn features on and off. You can listen for state changes with the quiet-input event and submit them with forms by adding name and value attributes.

Assistive devices will recognize toggle icons as toggle buttons . The default icon is a star, but you can customize it with any icon you want. 

<quiet-toggle-icon 
  label="Star this"
  effect="fade"
></quiet-toggle-icon>

<quiet-toggle-icon 
  label="Save to favorites"
  effect="scale"
  style="--checked-color: crimson;"
>
  <quiet-icon slot="unchecked" name="heart" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="heart" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Like this post"
  effect="flip-x"
  style="--checked-color: dodgerblue;"
>
  <quiet-icon slot="unchecked" name="thumb-up" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="thumb-up" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Play / pause"
  effect="scale"
  style="
    --checked-color: var(--quiet-neutral-fill-mid); 
    --unchecked-color: var(--quiet-neutral-fill-mid);
  "
>
  <quiet-icon slot="unchecked" name="player-pause" family="filled"></quiet-icon>
  <quiet-icon slot="checked" name="player-play" family="filled"></quiet-icon>
</quiet-toggle-icon>

Examples Jump to heading

Checked initially Jump to heading

Add the checked attribute to check the toggle icon initially.

<quiet-toggle-icon 
  label="Star this"
  name="favorite" 
  value="1" 
  checked
></quiet-toggle-icon>

Custom icons Jump to heading

Place a <quiet-icon> into the default slot to show a custom unchecked state. Place one into the checked slot to show a custom checked state.

You can use any icon you want for each state, but outline for unchecked icons and filled for checked icons usually work best. Use the --unchecked-color and --checked-color custom properties to change colors. 

<quiet-toggle-icon 
  label="Save to favorites"
  style="--checked-color: crimson;"
>
  <quiet-icon slot="unchecked" name="heart" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="heart" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Like this post"
  style="--checked-color: dodgerblue;"
>
  <quiet-icon slot="unchecked" name="thumb-up" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="thumb-up" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Enable filter" 
  style="--checked-color: blueviolet;"
>
  <quiet-icon slot="unchecked" name="filter" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="filter" family="filled"></quiet-icon>
</quiet-toggle-icon>

Changing the effect Jump to heading

Set the effect attribute to change the toggle icon's animation. This works great with custom icons. 

<quiet-toggle-icon 
  label="Star this"
  effect="fade"
></quiet-toggle-icon>

<quiet-toggle-icon 
  label="Love this"
  effect="scale" 
  style="--checked-color: crimson;"
>
  <quiet-icon slot="unchecked" name="heart" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="heart" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Mark as complete"
  effect="flip-x" 
  style="--checked-color: cadetblue;"
>
  <quiet-icon slot="unchecked" name="clipboard" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="clipboard-check" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Secure this"
  effect="flip-y" 
  style="--checked-color: forestgreen;"
>
  <quiet-icon slot="unchecked" name="shield" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="shield-check" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Ship this"
  effect="translate-x" 
  style="--checked-color: blueviolet;"
>
  <quiet-icon slot="unchecked" name="truck" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="truck" family="filled"></quiet-icon>
</quiet-toggle-icon>

<quiet-toggle-icon 
  label="Enable reader mode"
  effect="translate-y" 
  style="--checked-color: dodgerblue;"
>
  <quiet-icon slot="unchecked" name="eyeglass" family="outline"></quiet-icon>
  <quiet-icon slot="checked" name="eyeglass" family="filled"></quiet-icon>
</quiet-toggle-icon>

Sizes Jump to heading

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

<quiet-toggle-icon size="xs"></quiet-toggle-icon>
<quiet-toggle-icon size="sm"></quiet-toggle-icon>
<quiet-toggle-icon size="md"></quiet-toggle-icon>
<quiet-toggle-icon size="lg"></quiet-toggle-icon>
<quiet-toggle-icon size="xl"></quiet-toggle-icon>

Disabling Jump to heading

Use the disabled attribute to disable the toggle icon.

<quiet-toggle-icon disabled></quiet-toggle-icon>
<quiet-toggle-icon checked disabled></quiet-toggle-icon>

Validation Jump to heading

The required attribute can be applied to enable validation using the Constraint Validation API . This will prevent form submission until the toggle icon is checked.



Submit Reset 
<form action="about:blank" method="get" target="_blank">
  <quiet-toggle-icon 
    label="Star this"
    name="star" 
    value="1" 
    required
  ></quiet-toggle-icon>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Using custom validation Jump to heading

Use the setCustomValidity() method to make the toggle icon invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.



Submit Reset 
<form action="about:blank" method="get" target="_blank" id="toggle__custom-validation">
  <quiet-toggle-icon 
    label="Star this"
    name="star" 
    value="1" 
    required
  ></quiet-toggle-icon>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<script type="module">
  import { allDefined } from '/dist/quiet.js';

  await allDefined();

  const form = document.getElementById('toggle__custom-validation');
  const toggleIcon = form.querySelector('quiet-toggle-icon');

  toggleIcon.setCustomValidity('Not so fast, bubba!');
</script>

Styling validation Jump to heading

You can style valid and invalid toggle icons using the :valid and :invalid pseudo classes.



Submit Reset 
<form action="about:blank" method="get" target="_blank" class="toggle__validation-pseudo">
  <quiet-toggle-icon 
    label="Star this"
    name="star" 
    value="1" 
    required
  ></quiet-toggle-icon>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .toggle__validation-pseudo {
    quiet-toggle-icon:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-toggle-icon:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.



Submit Reset 
<form action="about:blank" method="get" target="_blank" class="toggle__validation-custom">
  <quiet-toggle-icon 
    label="Star this"
    name="star" 
    value="1" 
    required
  ></quiet-toggle-icon>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .toggle__validation-custom {
    quiet-toggle-icon:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-toggle-icon:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN npm

To manually import <quiet-toggle-icon> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet-browser@1.0.0/dist/components/toggle-icon/toggle-icon.js';

To manually import <quiet-toggle-icon> from npm, use the following code.

import '@quietui/quiet/dist/components/toggle-icon/toggle-icon.js';

Slots Jump to heading

Toggle Icon supports the following slots. Learn more about using slots

Name Description
checked The icon to show when checked. Works best with a <quiet-icon> element.
unchecked The default icon to show when unchecked. Works best with a <quiet-icon> element.

Properties Jump to heading

Toggle Icon has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute Description Reflects Type Default
label The toggle icon's label. The label won't be displayed, but it will be announced by assistive devices. string
name The name of the toggle icon. This will be submitted with the form as a name/value pair. string
value The toggle icon's value. string ''
checked The toggle icon's checked state. boolean false
disabled Disables the toggle icon. boolean false
size The checkbox's size. 'xs'
'sm'
'md'
'lg'
'xl' 		'md'
effect The animation to use when toggling. 'fade'
'scale'
'flip-x'
'flip-y'
'translate-x'
'translate-y'
'none' 		'none'
form The form to associate this control with. If omitted, the closest containing <form> will be used. The value of this attribute must be an ID of a form in the same document or shadow root. string
required Makes the toggle icon required. Form submission will not be allowed until the toggle icon is checked. boolean false

Events Jump to heading

Toggle Icon dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name Description
change
input
quiet-blur Emitted when the toggle icon loses focus. This event does not bubble.
quiet-change Emitted when the user commits changes to the toggle's value.
quiet-focus Emitted when the checkbox receives focus. This event does not bubble.
quiet-input Emitted when the checkbox receives input.

CSS custom properties Jump to heading

Toggle Icon supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name Description Default
--animation-speed The animation speed to use when effects are selected. 300ms
--checked-color The color to use for checked toggle icons. #f59e0b
--unchecked-color The color to use for unchecked toggle icons. var(--quiet-neutral-fill-mid)

CSS parts Jump to heading

Toggle Icon exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name Description CSS selector
button The internal button that contains the toggle icons, a <button> element. ::part(button)

Custom States Jump to heading

Toggle Icon has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name Description CSS selector
checked Applied when the toggle icon is active. :state(checked)
disabled Applied when the toggle icon is disabled. :state(disabled)
focused Applied when the toggle icon has focus. :state(focused)
user-valid Applied when the toggle icon is valid and the user has sufficiently interacted with it. :state(user-valid)
user-invalid Applied when the toggle icon is invalid and the user has sufficiently interacted with it. :state(user-invalid)
Search this website Toggle dark mode Get the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X

    No results found