# Toggle
Package: @mantine/core
Import: import { Toggle } from '@mantine/core';
Description: A toggleable button with active/inactive states

## Usage

`Toggle` is a button that can be toggled between active and inactive states.
It is a polymorphic component and can be rendered as any element.

```tsx
import { TextBIcon, TextItalicIcon, TextUnderlineIcon } from '@phosphor-icons/react';
import { Group, Toggle } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <Toggle aria-label="Bold">
        <TextBIcon weight="bold" size="100%" />
      </Toggle>
      <Toggle aria-label="Italic">
        <TextItalicIcon weight="bold" size="100%" />
      </Toggle>
      <Toggle aria-label="Underline">
        <TextUnderlineIcon weight="bold" size="100%" />
      </Toggle>
    </Group>
  );
}
```


## Controlled and uncontrolled

Use `defaultActive` to set the initial state of an uncontrolled `Toggle`,
`active` and `onActiveChange` props to control it.

```tsx
import { useState } from 'react';
import { Toggle } from '@mantine/core';

// Uncontrolled
function UncontrolledDemo() {
  return <Toggle defaultActive />;
}

// Controlled
function ControlledDemo() {
  const [active, setActive] = useState(false);
  return <Toggle active={active} onActiveChange={setActive} />;
}
```

## Auto contrast

Set `autoContrast` prop to automatically adjust icon color based on the active toggle
background color, for example with `variant="filled"` and light colors.

```tsx
import { TextBIcon } from '@phosphor-icons/react';
import { Group, Toggle } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <Toggle active variant="filled" color="lime.4" aria-label="Without autoContrast">
        <TextBIcon weight="bold" size="100%" />
      </Toggle>
      <Toggle autoContrast active variant="filled" color="lime.4" aria-label="With autoContrast">
        <TextBIcon weight="bold" size="100%" />
      </Toggle>
    </Group>
  );
}
```


## Auto width

By default, `Toggle` renders as a square button. Set `autoWidth` to allow
the width to adjust to content.

```tsx
import { Group, Toggle } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <Toggle autoWidth>Save</Toggle>
      <Toggle autoWidth active>Active</Toggle>
      <Toggle autoWidth disabled>Disabled</Toggle>
    </Group>
  );
}
```


## Configurator

```tsx
import { TextBIcon } from '@phosphor-icons/react';
import { Toggle } from '@mantine/core';

function Demo() {
  return (
    <Toggle variant="filled" color="blue" size="md" radius="md" autoContrast={false} disabled={false} aria-label="Bold">
      <TextBIcon weight="bold" size="100%" />
    </Toggle>
  );
}
```


## Accessibility

`Toggle` renders a `button` element with `aria-pressed` attribute that reflects the active state.
When using icon-only toggles, provide an `aria-label` prop so that screen readers can
announce the button purpose.

When `Toggle` is rendered as a non-button element (for example, `component="a"`), the `disabled` prop
sets `aria-disabled`, removes the element from the tab order and prevents clicks.


#### Props

**Toggle props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| active | boolean | - | Controlled active state |
| autoContrast | boolean | - | Determines whether icon color with filled variant should be changed based on the given `color` prop |
| autoWidth | boolean | - | If set, the toggle width adjusts to content instead of being square, `false` by default |
| color | MantineColor | - | Key of `theme.colors` or any valid CSS color, `theme.primaryColor` by default |
| defaultActive | boolean | - | Uncontrolled default active state |
| disabled | boolean | - | If set, the toggle is disabled |
| onActiveChange | (active: boolean) => void | - | Called when active state changes |
| radius | MantineRadius \| number | - | Key of `theme.radius` or any valid CSS value to set `border-radius`, `theme.defaultRadius` by default |
| size | MantineSize | - | Controls toggle height and min-width, `'md'` by default |


#### Styles API

Toggle component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Toggle selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-Toggle-root | Root element |

**Toggle CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --toggle-size | Controls toggle `height` and `min-width` |
| root | --toggle-radius | Controls `border-radius` |
| root | --toggle-active-bg | Controls active state `background-color` |
| root | --toggle-active-hover | Controls active state hover `background-color` |
| root | --toggle-active-color | Controls active state text `color` |

**Toggle data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-active | Toggle is in active state | - |
| root | data-disabled | `disabled` prop is set | - |
| root | data-auto-width | `autoWidth` prop is set | - |