UI Kit components
UI Kit hooks
Forge bridge APIs
Jira bridge APIs
Upgrade UI Kit versions
Previous versions


To add the Toggle component to your app:

import { Toggle } from '@forge/react';


A toggle is used to view or switch between enabled or disabled states.


defaultCheckedbooleanNoWhether the toggle is initially checked or not. After the initial interaction, whether the component is checked or not is controlled by the component.
idstringNoUse a pairing label with your toggle using id and labelFor props to set the relationship.
isCheckedbooleanNoIf defined it takes precedence over defaultChecked and Toggle acts as a controlled component. You can provide an onChange function to be notified of checked value changes.
isDisabledbooleanNoSets if the toggle is disabled or not. This prevents any interaction. Keep in mind that disabled toggles will not be available to screen readers.
labelstringNoText to be used as aria-label of toggle component.

Use this when there is no visible label for the toggle.

namestringNoDescriptive name for value property to be submitted in a form.
onBlur(event: FocusEvent) => voidNoHandler to be called when toggle is unfocused.
onChange(event: ChangeEvent) => voidNoHandler to be called when native 'change' event happens internally.
onFocus(event: FocusEvent) => voidNoHandler to be called when toggle is focused.
size"regular" | "large"NoToggle size.
valuestringNoValue to be submitted in a form.



The default form of a toggle.

Example image of a rendered default toggle

import { Label, Toggle } from "@forge/react";

export default function ToggleExample() {
  return (
    <Toggle id="toggle-default" />



Manage the checked state of the input by providing the isChecked prop. This requires an onChange handler to control the state value that you pass into the isChecked prop.

Example image of a rendered controlled toggle

import React, { useState } from "react";
import { Label, Toggle } from "@forge/react";

export default function ToggleControlledExample() {
  const [isChecked, setIsChecked] = useState(false);

  return (
        onChange={() => setIsChecked((prev) => !prev)}
      <Label labelFor="toggle">Field label</Label>



When a selection has already been made outside of the current context that negates the need for the toggle, you can use the disabled state.

Example image of a disabled toggle

export default function ToggleDisabledExample() {
  return (
    <Toggle id="toggle-disabled" isDisabled defaultChecked />


To call attention to a specific action, use a large toggle.

Example image of a large toggle

export default function ToggleLargeExample() {
  return (
    <Toggle size="large" />

Toggle with hidden label

Always use the label prop when there isn't a visible label that you can pair the toggle with.

Example image of a toggle with a hidden label

export default function ToggleLabelExample() {
  return (
    <Toggle id="toggle-default" label="This label is hidden" />

Accessibility considerations

When using the Toggle component, we recommend to keep the following accessibility considerations in mind:

  • If you're using a disabled toggle, include information explaining why the option isn't available. You can also use visually hidden to tell people who use screen readers that there is an option that isn't available to them.
  • Avoid changing the toggle label based on the on or off state. The label should be the same regardless of the current toggle setting.
  • Label your toggle using a Label component that properly describes your Toggle component.

Rate this page: