A binary setting that applies immediately, with Checkbox's form and validation behavior.
<tp-switch>
Switch
Default density
Compact density
Restart from the initial state
Show the copyable source
<tp-field orientation="horizontal" label="Product updates" description="Email me about new features and releases.">
<tp-switch name="product-updates" default-checked></tp-switch>
</tp-field>
Usage
Use a Switch for a setting that takes effect as soon as it flips, such as turning notifications on. When the choice only applies after a Save or Submit, a Checkbox reads more honestly. Name the Switch with a horizontal tp-field, which also carries its description and errors. Text in the default slot is a visible label through the library Label component; authored host aria-label and Field association can supply the name instead. Native HTML labels also work: a wrapping label or for matching the Switch host’s id activates the existing Boolean owner.
Settings list
Settings
Default density
Compact density
Restart from the initial state
Show the copyable source
<div style="display:grid;gap:var(--tp-space-5);max-inline-size:26rem;margin-inline:auto">
<tp-field orientation="horizontal" label="Two-factor authentication" description="Require a code from your authenticator app.">
<tp-switch name="two-factor" default-checked></tp-switch>
</tp-field>
<tp-field orientation="horizontal" label="Login alerts" description="Notify me when a new device signs in.">
<tp-switch name="login-alerts"></tp-switch>
</tp-field>
<tp-field orientation="horizontal" label="Session timeout" description="Sign out after 30 minutes of inactivity.">
<tp-switch name="session-timeout" default-checked></tp-switch>
</tp-field>
</div>
Sizes
Sizes
Default density
Compact density
Restart from the initial state
Show the copyable source
Without a visible label, name the Switch with aria-label.
Forms
A checked Switch submits its value (on by default) under its name; an unchecked one submits nothing unless you set unchecked-value. required makes unchecked a missing value that blocks submission.
Form value
Default density
Compact density
Restart from the initial state
Show the copyable source
Save preferences
Save preferences
<tp-form style="display:grid;gap:var(--tp-space-5);max-inline-size:26rem;margin-inline:auto">
<tp-field orientation="horizontal" label="Public profile" description="Show your name and avatar to other workspaces.">
<tp-switch name="visibility" value="public" unchecked-value="private"></tp-switch>
</tp-field>
<tp-field orientation="horizontal" label="Weekly digest" description="A Monday summary of activity in your projects.">
<tp-switch name="digest" default-checked></tp-switch>
</tp-field>
<div slot="actions">
<tp-button type="submit">Save preferences</tp-button>
</div>
</tp-form>
States
Disabled and read-only
Default density
Compact density
Restart from the initial state
Show the copyable source
<div style="display:grid;gap:var(--tp-space-5);max-inline-size:26rem;margin-inline:auto">
<tp-field orientation="horizontal" label="Single sign-on" description="Available on the Enterprise plan.">
<tp-switch name="sso" disabled></tp-switch>
</tp-field>
<tp-field orientation="horizontal" label="Audit logging" description="Managed by your organization.">
<tp-switch name="audit" default-checked readonly></tp-switch>
</tp-field>
</div>
Disabled removes the Switch from the tab order and from form data. Read-only stays focusable and submitted, but rejects changes.
Controlled
Set checked to drive the Switch from your own state. Every flip then arrives as a proposal in onCheckedChange, and the Switch only moves when you write the accepted value back synchronously. Here the digest follows the master setting: turning email off also turns it off and locks it. The callback runs before the cancelable DOM event. A later DOM veto rolls back a synchronous owner return, so read the committed getter after the transaction when publishing outside state.
Controlled
Default density
Compact density
Restart from the initial state
Show the copyable source
Content in the thumb slot rides along with the Thumb, such as an icon that confirms the state at a glance. It is decorative, so the Switch still needs its own name.
Thumb icon
Default density
Compact density
Restart from the initial state
Show the copyable source
Default density
Compact density
Restart from the initial state
Show the copyable source
<div style="display:flex;align-items:center;gap:var(--tp-space-4)">
<tp-switch id="switch-demo-wifi" aria-label="Wi-Fi" default-checked></tp-switch>
<output id="switch-demo-status" aria-live="polite">Wi-Fi is on</output>
</div>
<script type="module">
const control = document.querySelector('#switch-demo-wifi');
const status = document.querySelector('#switch-demo-status');
control.addEventListener('tp-value-change', (event) => {
status.textContent = event.detail.value ? 'Wi-Fi is on' : 'Wi-Fi is off';
});
</script>
tp-value-change is cancelable and carries the proposed checked value. Calling preventDefault() keeps the current state, which is how you veto a change that needs confirmation first.
Inline
Inline
Default density
Compact density
Restart from the initial state
Show the copyable source
variant="inline" fits the Switch into one row the height of a control, with its label at the start and the track at the end, so it stacks with other inline controls such as an inline Select. A press anywhere on the row flips it. Inside a Field and without a label of its own, the Field’s label moves into the row.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptionsizesize'sm' | 'default''default'The size of the track and thumb; sm suits dense rows and toolbars.
Events
EventTypeDescriptiontp-value-changeTpValueChangeEvent<boolean>Cancelable proposal of a new checked state before it commits; detail.value, detail.previousValue and the detail.reason for the change.tp-field-valueCustomEvent<{ value: boolean; previousValue: boolean; reason: ChangeReason; }>After the checked state commits, with the same value, previousValue and reason; the enclosing Field listens for it.
Slots
SlotDescriptiondefaultThe inline label; a press on it toggles the switch.thumbDecorative content inside the thumb, such as a small icon.
CSS parts
PartDescription::part(switch-row)The row of an inline Switch around its label and track.::part(checkbox-indicator)The check or mixed mark inside the box, shown while checked or mixed.::part(switch-thumb)The thumb that slides along the track; holds the thumb slot.
Related
Components, widgets and patterns that use this one.