Switch

Switches allow the user to toggle an option on or off.

<pc-switch>Switch</pc-switch>

Code

This component works well with standard <form> elements. Please refer to the form controls page to learn more about form submission and client‐side validation.

Demos

Checked

Use the checked attribute to set the switch’s state to enabled.

<pc-switch checked>Checked</pc-switch>

Code

Disabled

Use the disabled attribute to disable the switch.

<pc-switch disabled>Disabled</pc-switch>

Code

Sizes

Use the size attribute to change a switch’s size.

<pc-switch size="small">Small</pc-switch>
<br />
<pc-switch size="medium">Medium</pc-switch>
<br />
<pc-switch size="large">Large</pc-switch>

Code

Hint

Add a descriptive hint to a switch with the hint attribute. For hints that contain HTML, use the hint slot instead.

<pc-switch
  hint="What should the user know about the switch?"
>
  Label
</pc-switch>

Code

Custom styles

Use the available custom properties to change how the switch is styled.

<pc-switch
  style="--width: 70px; --height: 40px; --thumb-size: 32px"
>
  A really large switch
</pc-switch>

Code

Properties

Name	Description	Default
`name`	The name of the switch, submitted as a name/value pair with form data. `string`	`""`
`value`	The current value of the switch, submitted as a name/value pair with form data. `string \| undefined`	-
`size`	The switch’s size. `"small" \| "medium" \| "large"`	`"medium"`
`disabled`	Disables the switch. `boolean`	`false`
`checked`	Enables the switch. `boolean`	`false`
`defaultChecked`	The default value of the switch. Primarily used for resetting the switch. `boolean`	`false`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. `string`	`""`
`required`	Makes the switch a required field. `boolean`	`false`
`hint`	The switch’s hint. if you need to display HTML, use the `hint` slot instead. `string`	`""`
`validity`	Gets the validity state object.	-
`validationMessage`	Gets the validation message.	-
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	-

Learn more about attributes and properties.

Slots

Name	Description
(default)	The switch’s label.
`hint`	Text that describes how to use the switch. Alternatively, you can use the `hint` attribute.

Learn more about using slots.

Methods

Name	Description	Arguments
`click()`	Simulates a click on the switch.	-
`focus()`	Focuses the switch.	`options: FocusOptions`
`blur()`	Unfocuses/blurs the switch.	-
`checkValidity()`	Checks for validity but doesn’t show a validation message. Returns `true` when valid and `false` when invalid.	-
`getForm()`	Gets the associated form if one exists.	-
`reportValidity()`	Checks for validity and shows the browser’s validation message if the control is invalid.	-
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`

Learn more about methods.

Events

Name	Description	Event detail
`pc-change`	Emitted when the switch’s state changes.	-
`pc-focus`	Emitted when the switch gains focus.	-
`pc-blur`	Emitted when the switch loses focus (i.e. is blurred).	-
`pc-input`	Emitted when the switch receives input.	-
`pc-invalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	-

Learn more about events.

Custom properties

Name	Description	Default
`--width`	The width of the switch.	-
`--height`	The height of the switch.	-
`--thumb-size`	The size of the thumb.	-

Learn more about customising custom properties.

Parts

Name	Description
`base`	The component’s base wrapper.
`control`	The control that houses the switch’s thumb.
`thumb`	The switch’s thumb.
`label`	The switch’s label.
`hint`	The hint’s wrapper.

Learn more about customising CSS parts.

Importing

If you’re using the autoloader or the standard loader, you can ignore this section. If you’re cherry picking, you can use any of the following snippets to import this component.

Script

Import

Bundler

To import this component from the CDN with a script tag, copy this snippet and paste it in your HTML.

<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/switch/switch.js"></script>

To import this component from the CDN using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/switch/switch.js";

To import this component with a bundler using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "placer-toolkit/dist/components/switch/switch.js";