monday-ui-react-core/src/components/Toggle/__stories__/Toggle.mdx

Official monday.com UI resources for application development in React.js

import { Meta } from "@storybook/blocks";
import Toggle from "../Toggle";
import {
  BUTTON_GROUP,
  CHECKBOX,
  RADIO_BUTTON
} from "../../../storybook/components/related-components/component-description-map";
import { ComponentRules, Link, UsageGuidelines } from "vibe-storybook-components";
import { TipOtherComponents } from "./Toggle.stories.helpers";
import * as ToggleStories from "./Toggle.stories";
import "./Toggle.stories.scss";

<Meta of={ToggleStories} />

# Toggle

- [Overview](#overview)
- [Props](#props)
- [Usage](#usage)
- [Variants](#variants)
- [Do’s and don’ts](#dos-and-donts)
- [Use cases and examples](#use-cases-and-examples)
- [Related components](#related-components)
- [Feedback](#feedback)

## Overview

Allow users to turn an single option on or off. They are usually used to activate or deactivate a specific setting.

<Canvas of={ToggleStories.Overview} />

## Props

<PropsTable />

## Usage

<UsageGuidelines
  guidelines={[
    "Use toggles when your intent is to turn something on or off instantly.",
    "Let users know what happens when the toggle is switched by using a tooltip.",
    <>
      Toggle can either be selected or not selected. They cannot be in an indeterminate state (unlike{" "}
      <StorybookLink page="Inputs/Checkbox">checkboxes</StorybookLink>).
    </>,
    "Use labels such as “on” and “off” or “enable” and “disable” to communicate the state of the toggle."
  ]}
/>

<TipOtherComponents />

## Variants

### States

<Canvas of={ToggleStories.States} />

### Size

Toggle appear in 2 sizes: small and medium.

<Canvas of={ToggleStories.Size} />

### Disabled

<Canvas of={ToggleStories.Disabled} />

## Do’s and Don’ts

<ComponentRules
  rules={[
    {
      positive: {
        component: (
          <div className="monday-storybook-toggle_row">
            Dark mode <Toggle />
          </div>
        ),
        description: "Use toggle only for on and off actions. We recommend not to change these lables values."
      },
      negative: {
        component: (
          <div className="monday-storybook-toggle_row">
            Theme <Toggle offOverrideText="Light mode" onOverrideText="Dark mode" />
          </div>
        ),
        description: (
          <>
            Don’t use toggle for configurations. Instead, use{" "}
            <StorybookLink page="Inputs/Checkbox">Checkboxes</StorybookLink> or{" "}
            <StorybookLink page="Inputs/RadioButton">Radio buttons.</StorybookLink>{" "}
          </>
        )
      }
    },
    {
      positive: {
        component: <Toggle />,
        description: "Toggle will always appear with labels"
      },
      negative: {
        component: (
          <div className="monday-storybook-toggle_column">
            <Toggle offOverrideText="" />
            <Toggle areLabelsHidden />
          </div>
        ),
        description: "Don’t remove toggle labels, since users would not know what state it represents. "
      }
    }
  ]}
/>

## Use cases and examples

### Turn on/ off an automation

In the automations center, a user can turn the automation on or off.

<Canvas of={ToggleStories.TurnOnOffAnAutomation} />

## Related components

<RelatedComponents componentsNames={[CHECKBOX, RADIO_BUTTON, BUTTON_GROUP]} />