Toggle Tag
<quiet-toggle-tag>
Similar to checkboxes, except with tags to represent the checked and unchecked states.
Toggle tags 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.
Toggle tags should generally be used in groups. In fact, they work best when place inside of checkbox groups. Assistive devices will recognize tag checkboxes as standard checkboxes.
<quiet-checkbox-group label="Amenities" style="--gap: .5em; max-width: 460px;"> <quiet-toggle-tag name="amenities" value="coffee"> <quiet-icon name="coffee"></quiet-icon> Coffee </quiet-toggle-tag> <quiet-toggle-tag name="amenities" value="laundry"> <quiet-icon name="wash-machine"></quiet-icon> Laundry </quiet-toggle-tag> <quiet-toggle-tag name="amenities" value="microwave"> <quiet-icon name="microwave"></quiet-icon> Microwave </quiet-toggle-tag> <quiet-toggle-tag name="amenities" value="parking"> <quiet-icon name="parking"></quiet-icon> Parking </quiet-toggle-tag> <quiet-toggle-tag name="amenities" value="pet-friendly"> <quiet-icon name="cat"></quiet-icon> Pet friendly </quiet-toggle-tag> <quiet-toggle-tag name="amenities" value="pool"> <quiet-icon name="pool"></quiet-icon> Pool </quiet-toggle-tag> <quiet-toggle-tag name="amenities" value="tv"> <quiet-icon name="device-tv"></quiet-icon> TV </quiet-toggle-tag> <quiet-toggle-tag name="amenities" value="wifi"> <quiet-icon name="wifi"></quiet-icon> Wifi </quiet-toggle-tag> </quiet-checkbox-group>
Examples Jump to heading
Checked initially Jump to heading
Add the checked attribute to check the toggle tag initially.
<quiet-checkbox-group label="Default notifications" style="--gap: .5em;"> <quiet-toggle-tag name="notifications" value="email" checked> <quiet-icon name="mail"></quiet-icon> Email updates </quiet-toggle-tag> <quiet-toggle-tag name="notifications" value="push" checked> <quiet-icon name="bell"></quiet-icon> Push notifications </quiet-toggle-tag> <quiet-toggle-tag name="notifications" value="sms"> <quiet-icon name="message-circle"></quiet-icon> SMS alerts </quiet-toggle-tag> <quiet-toggle-tag name="notifications" value="phone"> <quiet-icon name="phone"></quiet-icon> Phone calls </quiet-toggle-tag> </quiet-checkbox-group>
Changing the size Jump to heading
Use the size attribute to make toggle tags larger or smaller. The available sizes are
xs, sm, md (default), lg, and xl.
<div style="display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;"> <div> <label style="display: block; margin-block-end: 0.5rem; font-weight: 600;">Extra small</label> <quiet-checkbox-group style="--gap: .5em;"> <quiet-toggle-tag size="xs" name="xs-sizes" value="xs">XS</quiet-toggle-tag> <quiet-toggle-tag size="xs" name="xs-sizes" value="s">S</quiet-toggle-tag> <quiet-toggle-tag size="xs" name="xs-sizes" value="m">M</quiet-toggle-tag> <quiet-toggle-tag size="xs" name="xs-sizes" value="l">L</quiet-toggle-tag> <quiet-toggle-tag size="xs" name="xs-sizes" value="xl">XL</quiet-toggle-tag> </quiet-checkbox-group> </div> <div> <label style="display: block; margin-block-end: 0.5rem; font-weight: 600;">Small</label> <quiet-checkbox-group style="--gap: .5em;"> <quiet-toggle-tag size="sm" name="sm-sizes" value="xs">XS</quiet-toggle-tag> <quiet-toggle-tag size="sm" name="sm-sizes" value="s">S</quiet-toggle-tag> <quiet-toggle-tag size="sm" name="sm-sizes" value="m">M</quiet-toggle-tag> <quiet-toggle-tag size="sm" name="sm-sizes" value="l">L</quiet-toggle-tag> <quiet-toggle-tag size="sm" name="sm-sizes" value="xl">XL</quiet-toggle-tag> </quiet-checkbox-group> </div> <div> <label style="display: block; margin-block-end: 0.5rem; font-weight: 600;">Medium (default)</label> <quiet-checkbox-group style="--gap: .5em;"> <quiet-toggle-tag size="md" name="md-sizes" value="xs">XS</quiet-toggle-tag> <quiet-toggle-tag size="md" name="md-sizes" value="s">S</quiet-toggle-tag> <quiet-toggle-tag size="md" name="md-sizes" value="m">M</quiet-toggle-tag> <quiet-toggle-tag size="md" name="md-sizes" value="l">L</quiet-toggle-tag> <quiet-toggle-tag size="md" name="md-sizes" value="xl">XL</quiet-toggle-tag> </quiet-checkbox-group> </div> <div> <label style="display: block; margin-block-end: 0.5rem; font-weight: 600;">Large</label> <quiet-checkbox-group style="--gap: .5em;"> <quiet-toggle-tag size="lg" name="lg-sizes" value="xs">XS</quiet-toggle-tag> <quiet-toggle-tag size="lg" name="lg-sizes" value="s">S</quiet-toggle-tag> <quiet-toggle-tag size="lg" name="lg-sizes" value="m">M</quiet-toggle-tag> <quiet-toggle-tag size="lg" name="lg-sizes" value="l">L</quiet-toggle-tag> <quiet-toggle-tag size="lg" name="lg-sizes" value="xl">XL</quiet-toggle-tag> </quiet-checkbox-group> </div> <div> <label style="display: block; margin-block-end: 0.5rem; font-weight: 600;">Extra large</label> <quiet-checkbox-group style="--gap: .5em;"> <quiet-toggle-tag size="xl" name="xl-sizes" value="xs">XS</quiet-toggle-tag> <quiet-toggle-tag size="xl" name="xl-sizes" value="s">S</quiet-toggle-tag> <quiet-toggle-tag size="xl" name="xl-sizes" value="m">M</quiet-toggle-tag> <quiet-toggle-tag size="xl" name="xl-sizes" value="l">L</quiet-toggle-tag> <quiet-toggle-tag size="xl" name="xl-sizes" value="xl">XL</quiet-toggle-tag> </quiet-checkbox-group> </div> </div>
Disabling toggle tags Jump to heading
Use the disabled attribute to prevent interaction with toggle tags. Disabled tags will appear
faded and won't respond to clicks or keyboard input.
<quiet-checkbox-group label="Options" style="--gap: .5em;"> <quiet-toggle-tag name="options" value="option1">Option 1</quiet-toggle-tag> <quiet-toggle-tag name="options" value="option2" disabled>Option 2</quiet-toggle-tag> <quiet-toggle-tag name="options" value="option3">Option 3</quiet-toggle-tag> </quiet-checkbox-group>
Handling form submission Jump to heading
Toggle tags are form-associated custom elements that behave like native checkboxes when submitting forms.
When a toggle tag is checked, its name and value attributes are included in the
form data, just like a standard checkbox.
<form id="toggle-tag__form" action="about:blank" target="_blank"> <quiet-checkbox-group label="Languages" style="--gap: .5em; margin-bottom: 1rem;"> <quiet-toggle-tag name="languages" value="cpp">C++</quiet-toggle-tag> <quiet-toggle-tag name="languages" value="go">Go</quiet-toggle-tag> <quiet-toggle-tag name="languages" value="javascript" checked>JavaScript</quiet-toggle-tag> <quiet-toggle-tag name="languages" value="php">PHP</quiet-toggle-tag> <quiet-toggle-tag name="languages" value="python">Python</quiet-toggle-tag> <quiet-toggle-tag name="languages" value="qb">QBasic</quiet-toggle-tag> <quiet-toggle-tag name="languages" value="rust">Rust</quiet-toggle-tag> </quiet-checkbox-group> <quiet-button type="submit">Submit</quiet-button> </form>
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.
To manually import <quiet-toggle-tag> from the CDN, use the following code.
import 'https://cdn.jsdelivr.net/npm/@quietui/quiet-browser@1.0.0/dist/components/toggle-tag/toggle-tag.js';
To manually import <quiet-toggle-tag> from npm, use the following code.
import '@quietui/quiet/dist/components/toggle-tag/toggle-tag.js';
Slots Jump to heading
Toggle Tag supports the following slots. Learn more about using slots
| Name | Description |
|---|---|
| (default) |
The toggle tag's label. For plain-text labels, you can use the label attribute instead.
|
Properties Jump to heading
Toggle Tag 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 tag's label. If you need to provide HTML in the label, use the label slot
instead.
|
|
string
|
|
name
|
The name of the toggle tag. This will be submitted with the form as a name/value pair. |
|
string
|
|
value
|
The toggle tag's value. |
|
string
|
''
|
checked
|
The toggle tag's checked state. |
|
boolean
|
false
|
disabled
|
Disables the toggle tag. |
|
boolean
|
false
|
size
|
The toggle tag's size. |
|
'xs'
|
'md'
|
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 tag required. Form submission will not be allowed until the toggle tag is checked. |
|
boolean
|
false
|
Methods Jump to heading
Toggle Tag supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods
| Name | Description | Arguments |
|---|---|---|
focus() |
Sets focus to the toggle tag. | |
blur() |
Removes focus from the toggle tag. | |
checkValidity() |
Checks if the form control has any restraints and whether it satisfies them. If invalid,
false will be returned and the invalid event will be dispatched. If valid,
true will be returned.
|
|
reportValidity() |
Checks if the form control has any restraints and whether it satisfies them. If invalid,
false will be returned and the invalid event will be dispatched. In
addition, the problem will be reported to the user. If valid, true will be returned.
|
|
setCustomValidity() |
Sets a custom validation message for the form control. If this message is not an empty string, then the form control is considered invalid and the specified message will be displayed to the user when reporting validity. Setting an empty string clears the custom validity state. | message: string |
Events Jump to heading
Toggle Tag dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events
| Name | Description |
|---|---|
quiet-blur |
Emitted when the toggle tag loses focus. This event does not bubble. |
quiet-change |
Emitted when the user commits changes to the toggle tag's value. |
quiet-focus |
Emitted when the toggle tag receives focus. This event does not bubble. |
quiet-input |
Emitted when the toggle tag receives input. |
CSS parts Jump to heading
Toggle Tag exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts
| Name | Description | CSS selector |
|---|---|---|
label |
The <label> that wraps the entire control. |
::part(label)
|
Custom States Jump to heading
Toggle Tag 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 tag is checked. |
:state(checked)
|
disabled |
Applied when the toggle tag is disabled. |
:state(disabled)
|
focused |
Applied when the toggle tag has focus. |
:state(focused)
|
user-valid |
Applied when the toggle tag is valid and the user has sufficiently interacted with it. |
:state(user-valid)
|
user-invalid |
Applied when the toggle tag is invalid and the user has sufficiently interacted with it. |
:state(user-invalid)
|