Switch

The Switch component is used as an alternative for the checkbox component.

Props#

`aria-describedby`

Type

string

`aria-invalid`

Type

true

`aria-label`

Description

Defines the string that labels the checkbox element.

Type

string

`aria-labelledby`

Description

Refers to the id of the element that labels the checkbox element.

Type

string

`colorScheme`

Description

The visual color appearance of the component

Type

"whiteAlpha" | "blackAlpha" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink"

Default

blue

`defaultChecked`

Description

If true, the checkbox will be initially checked.

Type

boolean

Default

false

`id`

Description

id assigned to input

Type

string

`isChecked`

Description

If true, the checkbox will be checked. You'll need to pass onChange to update its value (since it is now controlled)

Type

boolean

Default

false

`isDisabled`

Description

If true, the checkbox will be disabled

Type

boolean

Default

false

`isFocusable`

Description

If true and isDisabled is passed, the checkbox will remain tabbable but not interactive

Type

boolean

Default

false

`isInvalid`

Description

If true, the checkbox is marked as invalid. Changes style of unchecked state.

Type

boolean

Default

false

`isReadOnly`

Description

If true, the checkbox will be readonly

Type

boolean

Default

false

`isRequired`

Description

If true, the checkbox input is marked as required, and required attribute will be added

Type

boolean

Default

false

`name`

Description

The name of the input field in a checkbox (Useful for form submission).

Type

string

`onBlur`

Description

The callback invoked when the checkbox is blurred (loses focus)

Type

(event: FocusEvent<HTMLInputElement, Element>) => void

`onChange`

Description

The callback invoked when the checked state of the Checkbox changes.

Type

(event: ChangeEvent<HTMLInputElement>) => void

`onFocus`

Description

The callback invoked when the checkbox is focused

Type

(event: FocusEvent<HTMLInputElement, Element>) => void

`size`

Description

The size of the Switch

Type

"sm" | "md" | "lg"

Default

md

`spacing`

Description

The spacing between the switch and its label text

Type

ResponsiveValue<string | number | (string & {})>

Default

0.5rem

`tabIndex`

Description

The tab-index property of the underlying input element.

Type

number

`value`

Description

The value to be used in the checkbox input. This is the value that will be returned on form submission.

Type

string | number

`variant`

Description

The variant of the Switch

Type

string

Props#

`aria-describedby`

Type

string

`aria-invalid`

Type

true

`aria-label`

Description

Defines the string that labels the checkbox element.

Type

string

`aria-labelledby`

Description

Refers to the id of the element that labels the checkbox element.

Type

string

`colorScheme`

Description

The visual color appearance of the component

Type

"whiteAlpha" | "blackAlpha" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink"

Default

blue

`defaultChecked`

Description

If true, the checkbox will be initially checked.

Type

boolean

Default

false

`id`

Description

id assigned to input

Type

string

`isChecked`

Description

If true, the checkbox will be checked. You'll need to pass onChange to update its value (since it is now controlled)

Type

boolean

Default

false

`isDisabled`

Description

If true, the checkbox will be disabled

Type

boolean

Default

false

`isFocusable`

Description

If true and isDisabled is passed, the checkbox will remain tabbable but not interactive

Type

boolean

Default

false

`isInvalid`

Description

If true, the checkbox is marked as invalid. Changes style of unchecked state.

Type

boolean

Default

false

`isReadOnly`

Description

If true, the checkbox will be readonly

Type

boolean

Default

false

`isRequired`

Description

If true, the checkbox input is marked as required, and required attribute will be added

Type

boolean

Default

false

`name`

Description

The name of the input field in a checkbox (Useful for form submission).

Type

string

`onBlur`

Description

The callback invoked when the checkbox is blurred (loses focus)

Type

(event: FocusEvent<HTMLInputElement, Element>) => void

`onChange`

Description

The callback invoked when the checked state of the Checkbox changes.

Type

(event: ChangeEvent<HTMLInputElement>) => void

`onFocus`

Description

The callback invoked when the checkbox is focused

Type

(event: FocusEvent<HTMLInputElement, Element>) => void

`size`

Description

The size of the Switch

Type

"sm" | "md" | "lg"

Default

md

`spacing`

Description

The spacing between the switch and its label text

Type

ResponsiveValue<string | number | (string & {})>

Default

0.5rem

`tabIndex`

Description

The tab-index property of the underlying input element.

Type

number

`value`

Description

The value to be used in the checkbox input. This is the value that will be returned on form submission.

Type

string | number

`variant`

Description

The variant of the Switch

Type

string

The Switch component is a multipart component. The styling needs to be applied to each part specifically.

To learn more about styling multipart components, visit the Component Style page.

Anatomy#

A: container
B: thumb
C: track

Theming properties#

The properties that affect the theming of the Switch component are:

colorScheme: The color scheme of the Switch component. Defaults to blue.
size: The size of the Switch component. Defaults to md.

Theming utilities#

createMultiStyleConfigHelpers: a function that returns a set of utilities for creating style configs for a multipart component (definePartsStyle and defineMultiStyleConfig).
definePartsStyle: a function used to create multipart style objects.
defineMultiStyleConfig: a function used to define the style configuration for a multipart component.

import { switchAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers } from '@chakra-ui/react'

const { definePartsStyle, defineMultiStyleConfig } =
  createMultiStyleConfigHelpers(switchAnatomy.keys)

Customizing the default theme#

import { switchAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers } from '@chakra-ui/react'

const { definePartsStyle, defineMultiStyleConfig } =
  createMultiStyleConfigHelpers(switchAnatomy.keys)

const baseStyle = definePartsStyle({
  // define the part you're going to style
  container: {
    // ...
  },
  thumb: {
    bg: 'red.500',
  },
  track: {
    bg: 'gray.100',
    _checked: {
      bg: 'gray.100',
    },
  },
})

export const switchTheme = defineMultiStyleConfig({ baseStyle })

After customizing the switch theme, we can import it in our theme file and add it in the components property:

import { extendTheme } from '@chakra-ui/react'
import { switchTheme } from './components/switch'

export const theme = extendTheme({
  components: { Switch: switchTheme },
})

This is a crucial step to make sure that any changes that we make to the switch theme are applied.

Using a custom color scheme#

Let's assume we want to use our own custom color scale based on our brand. We'd need to define the color scale first in the main theme file:

import { extendTheme } from '@chakra-ui/react'

export const theme = extendTheme({
  colors: {
    brand: {
      50: '#f7fafc',
      ...
      500: '#718096',
      ...
      900: '#171923',
    }
  }
})

Then, we can use the custom color scale as the color scheme for the button:

<Switch colorScheme='brand' />

Every time you're adding anything new to the theme, you'd need to run the CLI command to get proper autocomplete in your IDE. You can learn more about the CLI tool here.

Adding a custom variant#

Let's assume we want to include a custom boxy variant. Here's how you can do that:

import { switchAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers } from '@chakra-ui/react'

const { definePartsStyle, defineMultiStyleConfig } =
  createMultiStyleConfigHelpers(switchAnatomy.keys)

const boxy = definePartsStyle({
  track: {
    borderRadius: 'sm',
    p: 1,
  }
})

export const switchTheme = defineMultiStyleConfig({ variants: { boxy }})

// Now we can use the new `boxy` variant
<Switch variant="boxy"/>

Changing the default properties#

Let's assume we want to change the default size and color scheme of every switch in our app. Here's how we can do that:

import { switchAnatomy } from '@chakra-ui/anatomy'
import { createMultiStyleConfigHelpers, defineStyle } from '@chakra-ui/react'

const { defineMultiStyleConfig } = createMultiStyleConfigHelpers(
  switchAnatomy.keys,
)

export const switchTheme = defineMultiStyleConfig({
  defaultProps: {
    size: 'xl',
    colorScheme: 'brand',
  },
})

// This saves you time, instead of manually setting the size and variant every time you use an input:
<Switch size="xl" colorScheme="brand" ... />

Showcase#

import {
  Box, HStack, IconButton, Switch, useColorMode
} from "@chakra-ui/react";
import { FaMoon, FaSun } from "react-icons/fa";

export default function App() {
  const { toggleColorMode, colorMode } = useColorMode();

  return (
    <Box position="relative" h="100vh">
      <HStack spacing={8} p={12}>
        <Switch size="sm" />
        <Switch size="md" />
        <Switch size="lg" />
        <Switch size="sm" colorScheme='red' />
        <Switch size="md" colorScheme='green' />
        <Switch size="lg" colorScheme='purple' />
        <Switch variant="boxy" colorScheme='yellow' />
      </HStack>
      <IconButton
        aria-label="toggle theme"
        rounded="full"
        size="xs"
        position="absolute"
        bottom={4}
        left={4}
        onClick={toggleColorMode} icon={colorMode === "dark" ? <FaSun /> : <FaMoon />}
      />
    </Box>
  )
}

Open Sandbox

Edit this page on GitHub