Toggle
Examples
Checked
Disabled
Sizes
Help Text
Custom Styles
Importing
Slots
Properties
Events
Methods
Custom Properties
Parts

Toggle

<terra-toggle> | TerraToggle

Since 1.0

stable

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

Toggle

<terra-toggle>Toggle</terra-toggle>

import TerraToggle from '@nasa-terra/components/dist/react/toggle';

const App = () => <TerraToggle>Toggle</TerraToggle>;

This component works with standard <form> elements. Please refer to the section on form controls to learn more about form submission and client-side validation.

Examples

Checked

Use the checked attribute to activate the toggle.

Checked

<terra-toggle checked>Checked</terra-toggle>

import TerraToggle from '@nasa-terra/components/dist/react/toggle';

const App = () => <TerraToggle checked>Checked</TerraToggle>;

Disabled

Use the disabled attribute to disable the toggle.

Disabled

<terra-toggle disabled>Disabled</terra-toggle>

import TerraToggle from '@nasa-terra/components/dist/react/toggle';

const App = () => <TerraToggle disabled>Disabled</TerraToggle>;

Sizes

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

Small

Medium

Large

<terra-toggle size="small">Small</terra-toggle>
<br />
<terra-toggle size="medium">Medium</terra-toggle>
<br />
<terra-toggle size="large">Large</terra-toggle>

import TerraToggle from '@nasa-terra/components/dist/react/toggle';

const App = () => (
  <>
    <TerraToggle size="small">Small</TerraToggle>
    <br />
    <TerraToggle size="medium">Medium</TerraToggle>
    <br />
    <TerraToggle size="large">Large</TerraToggle>
  </>
);

Help Text

Add descriptive help text to a toggle with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

Label

<terra-toggle help-text="What should the user know about the toggle?">Label</terra-toggle>

import TerraToggle from '@nasa-terra/components/dist/react/checkbox';

const App = () => <TerraToggle help-text="What should the user know about the toggle?">Label</TerraToggle>;

Custom Styles

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

Really big

<terra-toggle style="--width: 80px; --height: 40px; --thumb-size: 36px;">Really big</terra-toggle>

import TerraToggle from '@nasa-terra/components/dist/react/toggle';

const App = () => (
  <TerraToggle
    style={{
      '--width': '80px',
      '--height': '32px',
      '--thumb-size': '26px'
    }}
  />
);

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script

Import

Bundler

React

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/toggle/toggle.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/toggle/toggle.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/toggle/toggle.js';

To import this component as a React component:

import TerraToggle from '@nasa-terra/components/dist/react/toggle';

Slots

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

Learn more about using slots.

Properties

Name	Description	Type	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`	-
`size`	The switch’s size.	`'small' \| 'medium' \| 'large'`	`'medium'`
`disabled`	Disables the switch.	`boolean`	`false`
`checked`	Draws the switch in a checked state.	`boolean`	`false`
`defaultChecked`	The default value of the form control. Primarily used for resetting the form control.	`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`
`helpText` `help-text`	The switch’s help text. If you need to display HTML, use the `help-text` 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.

Events

Name	React Event	Description	Event Detail
`terra-blur`	`onTerraBlur`	Emitted when the control loses focus.	-
`terra-change`	`onTerraChange`	Emitted when the control’s checked state changes.	-
`terra-input`	`onTerraInput`	Emitted when the control receives input.	-
`terra-focus`	`onTerraFocus`	Emitted when the control gains focus.	-
`terra-invalid`	`onTerraInvalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	-

Learn more about events.

Methods

Name	Description	Arguments
`click()`	Simulates a click on the switch.	-
`focus()`	Sets focus on the switch.	`options: FocusOptions`
`blur()`	Removes focus from the switch.	-
`checkValidity()`	Checks for validity but does not 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.

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 customizing CSS 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.
`form-control-help-text`	The help text’s wrapper.

Learn more about customizing CSS parts.