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

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

import { Meta } from "@storybook/blocks";
import Checkbox from "../Checkbox";
import { createComponentTemplate, Link } from "vibe-storybook-components";
import { createStoryMetaSettingsDecorator } from "../../../storybook";
import {
  DROPDOWN,
  RADIO_BUTTON,
  TOGGLE
} from "../../../storybook/components/related-components/component-description-map";
import DialogContentContainer from "../../DialogContentContainer/DialogContentContainer";
import { TipAmIUsingTheRightComponent } from "./Checkbox.stories.helpers";
import "./Checkbox.stories.scss";
import * as CheckboxStories from "./Checkbox.stories";

export const metaSettings = createStoryMetaSettingsDecorator({ component: Checkbox });

<Meta of={CheckboxStories} />

export const checkboxTemplate = createComponentTemplate(Checkbox);

# Checkbox

- [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

Checkboxes allow users to select one or more items from a set of options.

<Canvas of={CheckboxStories.Overview} />

## Props

<PropsTable />

## Usage

<UsageGuidelines
  guidelines={[
    <span className="monday-storybook-checkbox_list">
      <span>Use checkboxes to:</span>
      <span className="monday-storybook-checkbox_list-item">1. Select one or more options from a list</span>
      <span className="monday-storybook-checkbox_list-item">2. Turn an item on or off in a desktop environment</span>
    </span>,
    "Use checkboxes independently from each other: selecting one checkbox shouldn’t change the selection status of another checkbox in the list. The exception is when a checkbox is used to make a bulk selection.",
    "Ensure both label and input are clickable to select the checkbox field. ",
    "Keep a positive tone of voice. For example: “Turn on notifications” instead of “Turn off notifications”.",
    "Checkboxes should be listed according to a logical order.",
    "Place checkboxes vertically, using 16px spacing.",
    "Checkbox will always appear with a label."
  ]}
/>

<TipAmIUsingTheRightComponent />

## Variants

### States

Has 4 states: regular, hover, selected, and disabled.

<Canvas of={CheckboxStories.States} />

## Do’s and Don’ts

<ComponentRules
  rules={[
    {
      positive: {
        component: (
          <DialogContentContainer className="monday-storybook-checkbox_wrapper">
            <Checkbox label="Item 1" name="Item 1" />
            <Checkbox label="Item 2" name="Item 2" checked />
            <Checkbox label="Item 3" name="Item 3" checked />
          </DialogContentContainer>
        ),
        description: "Use checkboxes when one or more items can be selected."
      },
      negative: {
        component: (
          <DialogContentContainer className="monday-storybook-checkbox_wrapper">
            <Checkbox label="Item 1" name="Item 1" checked />
            <Checkbox label="Item 2" name="Item 2" disabled />
            <Checkbox label="Item 3" name="Item 3" disabled />
          </DialogContentContainer>
        ),
        description: (
          <>
            Don't use checkboxes when only one item can be selected from a list. Use{" "}
            <StorybookLink page="Inputs/RadioButton">radio buttons</StorybookLink> instead.
          </>
        )
      }
    },
    {
      positive: {
        component: (
          <div className="monday-storybook-checkbox_border">
            <Checkbox label="Option" checked />
          </div>
        ),
        description: "Use the checkbox label’s prop to describe the option purpse."
      },
      negative: {
        component: [
          <div className="monday-storybook-checkbox_border">
            <Checkbox className="monday-storybook-checkbox_minus-margin" checked />
          </div>,
          <div className="monday-storybook-checkbox_border">Option</div>
        ],
        description: "Don’t use a separte div which is not related to the Checkbox component."
      }
    },
    {
      positive: {
        component: (
          <DialogContentContainer className="monday-storybook-checkbox_wrapper">
            <Checkbox label="Item 1" name="Item 1" />
            <Checkbox label="Item 2" name="Item 2" checked />
            <Checkbox label="Item 3" name="Item 3" checked />
          </DialogContentContainer>
        ),
        description: "Place the checkbox on the left side of the label."
      },
      negative: {
        component: (
          <DialogContentContainer className="monday-storybook-checkbox_wrapper">
            <div className="monday-storybook-checkbox_inline-wrapper">
              <span>Item 1</span>
              <Checkbox className="monday-storybook-checkbox_minus-margin" />
            </div>
            <div className="monday-storybook-checkbox_inline-wrapper">
              <span>Item 2</span>
              <Checkbox className="monday-storybook-checkbox_minus-margin" checked />
            </div>
            <div className="monday-storybook-checkbox_inline-wrapper">
              <span>Item 3</span>
              <Checkbox className="monday-storybook-checkbox_minus-margin" checked />
            </div>
          </DialogContentContainer>
        ),
        description: "Don’t change the position of the checkbox. Keep it to the left side of the label."
      }
    },
    {
      positive: {
        component: (
          <DialogContentContainer className="monday-storybook-checkbox_wrapper">
            <Checkbox label="Only show incomplete items" checked />
          </DialogContentContainer>
        ),
        description: "Always keep a positive tone of voice."
      },
      negative: {
        component: (
          <DialogContentContainer className="monday-storybook-checkbox_wrapper">
            <Checkbox label="Hide done items" checked />
          </DialogContentContainer>
        ),
        description: "Avoid negative language that makes the user check the box in order for something not to happen."
      }
    }
  ]}
/>

## Use cases and examples

### Single checkbox

Allows the user to choose a single option. For example: accept terms of use.

<Canvas of={CheckboxStories.SingleCheckbox} />

## Related components

<RelatedComponents componentsNames={[RADIO_BUTTON, TOGGLE, DROPDOWN]} />