ToggleButton

ToggleButton allows users to toggle the on/off state for some configuration.

ARIA pattern Theme source React source Feedback

Demo

Usage

Import the ToggleButton primitive.

import { ToggleButton } from '@aws-amplify/ui-react';

export const DefaultToggleButtonExample = () => {
  return <ToggleButton>Press me!</ToggleButton>;
};

Controlled component

A toggle button can be a controlled component when given isPressed prop and onChange prop must be provided in this case.

import * as React from 'react';
import { ToggleButton } from '@aws-amplify/ui-react';

export const ControlledToggleButtonExample = () => {
  const [isPressed, setIsPressed] = React.useState(false);
  return (
    <ToggleButton
      isPressed={isPressed}
      onChange={() => setIsPressed(!isPressed)}
    >
      Press me!
    </ToggleButton>
  );
};

Sizes

Use the size prop to change the Button size. Available options are small, large, and none (default).

import { Flex, ToggleButton } from '@aws-amplify/ui-react';

export const ToggleButtonSizeExample = () => {
  return (
    <Flex>
      <ToggleButton size="small">Press me!</ToggleButton>
      <ToggleButton>Press me!</ToggleButton>
      <ToggleButton size="large">Press me!</ToggleButton>
    </Flex>
  );
};

Variations

Use the variation prop to change the Button variation. Available options are primary, link, and none (default).

import { Flex, ToggleButton } from '@aws-amplify/ui-react';

export const ToggleButtonVariationsExample = () => {
  return (
    <Flex>
      <ToggleButton defaultPressed>Press me!</ToggleButton>
      <ToggleButton variation="primary" defaultPressed>
        Press me!
      </ToggleButton>
      <ToggleButton variation="link" defaultPressed>
        Press me!
      </ToggleButton>
    </Flex>
  );
};

Disabled

A disabled toggle button will not be able to switch state and will not be focusable.

import { Flex, ToggleButton } from '@aws-amplify/ui-react';

export const DisabledToggleButtonExample = () => {
  return (
    <Flex>
      <ToggleButton isDisabled>Press me!</ToggleButton>
      <ToggleButton isDisabled defaultPressed>
        Press me!
      </ToggleButton>
    </Flex>
  );
};

ToggleButtonGroup

You can group related Toggle buttons easily with a ToggleButtonGroup out of box. To control the selected state of its child buttons, both value and onChange props must be provided.

import * as React from 'react';
import {
  MdFormatBold,
  MdFormatColorFill,
  MdFormatItalic,
  MdFormatUnderlined,
} from 'react-icons/md';
import { ToggleButton, ToggleButtonGroup } from '@aws-amplify/ui-react';

export const DefaultToggleButtonGroupExample = () => {
  const [multipleValue, setMultipleValue] = React.useState(['bold']);
  return (
    <ToggleButtonGroup
      value={multipleValue}
      onChange={(value) => setMultipleValue(value as string[])}
    >
      <ToggleButton value="bold">
        <MdFormatBold />
      </ToggleButton>
      <ToggleButton value="italic">
        <MdFormatItalic />
      </ToggleButton>
      <ToggleButton value="underlined">
        <MdFormatUnderlined />
      </ToggleButton>
      <ToggleButton value="color-fill">
        <MdFormatColorFill />
      </ToggleButton>
    </ToggleButtonGroup>
  );
};

To make your toggle button group exclusive, set the isExclusive prop to true.

import * as React from 'react';
import {
  MdFormatAlignCenter,
  MdFormatAlignJustify,
  MdFormatAlignLeft,
  MdFormatAlignRight,
} from 'react-icons/md';
import { ToggleButton, ToggleButtonGroup } from '@aws-amplify/ui-react';

export const ExclusiveToggleButtonGroupExample = () => {
  const [exclusiveValue, setExclusiveValue] = React.useState('align-left');
  return (
    <ToggleButtonGroup
      value={exclusiveValue}
      isExclusive
      onChange={(value) => setExclusiveValue(value as string)}
    >
      <ToggleButton value="align-left">
        <MdFormatAlignLeft />
      </ToggleButton>
      <ToggleButton value="align-center">
        <MdFormatAlignCenter />
      </ToggleButton>
      <ToggleButton value="align-right">
        <MdFormatAlignRight />
      </ToggleButton>
      <ToggleButton value="align-justify">
        <MdFormatAlignJustify />
      </ToggleButton>
    </ToggleButtonGroup>
  );
};

In cases where you need to have at least one option on, you can set the isSelectionRequired prop to true.

import * as React from 'react';
import {
  MdFormatBold,
  MdFormatColorFill,
  MdFormatItalic,
  MdFormatUnderlined,
} from 'react-icons/md';
import { ToggleButton, ToggleButtonGroup } from '@aws-amplify/ui-react';

export const SelectionRequiredToggleButtonGroupExample = () => {
  const [value, setValue] = React.useState('bold');
  return (
    <ToggleButtonGroup
      value={value}
      onChange={(value) => setValue(value as string)}
      isExclusive
      isSelectionRequired
    >
      <ToggleButton value="bold">
        <MdFormatBold />
      </ToggleButton>
      <ToggleButton value="italic">
        <MdFormatItalic />
      </ToggleButton>
      <ToggleButton value="underlined">
        <MdFormatUnderlined />
      </ToggleButton>
      <ToggleButton value="color-fill">
        <MdFormatColorFill />
      </ToggleButton>
    </ToggleButtonGroup>
  );
};

Standard HTML attributes

The ToggleButton will accept any of the standard HTML attributes that a <button> element accepts. Standard <button> attributes can be found in the MDN Documentation

<ToggleButton name="button">Press me!</ToggleButton>

CSS Styling

Theme

You can customize the appearance of all ToggleButton components in your application with a Theme.

ToggleButton Theme Source

import {
  ToggleButton,
  Flex,
  ThemeProvider,
  Theme,
} from '@aws-amplify/ui-react';

const theme: Theme = {
  name: 'toggleButton-theme',
  tokens: {
    components: {
      togglebutton: {
        borderColor: { value: '{colors.blue.90}' },
        color: { value: '{colors.blue.90}' },
        _hover: {
          backgroundColor: { value: '{colors.blue.40}' },
        },
        _focus: {
          color: { value: 'white' },
        },
        _active: {
          backgroundColor: { value: '{colors.blue.60}' },
        },
        _pressed: {
          backgroundColor: { value: '{colors.blue.80}' },
          color: { value: 'white' },
          _hover: {
            backgroundColor: { value: 'blue' },
          },
        },
        primary: {
          backgroundColor: { value: '{colors.teal.20}' },
        },
      },
    },
  },
};

export const ToggleButtonThemeExample = () => {
  return (
    <ThemeProvider theme={theme} colorMode="light">
      <Flex>
        <ToggleButton>Default</ToggleButton>
        <ToggleButton variation="primary">Primary</ToggleButton>
      </Flex>
    </ThemeProvider>
  );
};

Target classes

Class	Description
`amplify-togglebutton`	Top level element that wraps the ToggleButton primitive
`amplify-togglebuttongroup`	Top level element that wraps the ToggleButtonGroup primitive

--amplify-components-togglebutton-active-background-color
--amplify-components-togglebutton-border-color
--amplify-components-togglebutton-color
--amplify-components-togglebutton-disabled-background-color
--amplify-components-togglebutton-disabled-border-color
--amplify-components-togglebutton-disabled-color
--amplify-components-togglebutton-focus-border-color
--amplify-components-togglebutton-focus-color
--amplify-components-togglebutton-hover-background-color
--amplify-components-togglebutton-link-background-color
--amplify-components-togglebutton-link-color
--amplify-components-togglebutton-link-disabled-background-color
--amplify-components-togglebutton-link-disabled-color
--amplify-components-togglebutton-link-focus-background-color
--amplify-components-togglebutton-link-focus-color
--amplify-components-togglebutton-link-hover-background-color
--amplify-components-togglebutton-link-hover-color
--amplify-components-togglebutton-link-pressed-background-color
--amplify-components-togglebutton-link-pressed-color
--amplify-components-togglebutton-link-pressed-focus-background-color
--amplify-components-togglebutton-link-pressed-focus-color
--amplify-components-togglebutton-link-pressed-hover-background-color
--amplify-components-togglebutton-link-pressed-hover-color
--amplify-components-togglebutton-pressed-background-color
--amplify-components-togglebutton-pressed-border-color
--amplify-components-togglebutton-pressed-color
--amplify-components-togglebutton-pressed-hover-background-color
--amplify-components-togglebutton-primary-background-color
--amplify-components-togglebutton-primary-border-width
--amplify-components-togglebutton-primary-disabled-background-color
--amplify-components-togglebutton-primary-disabled-border-color
--amplify-components-togglebutton-primary-disabled-color
--amplify-components-togglebutton-primary-focus-background-color
--amplify-components-togglebutton-primary-focus-border-color
--amplify-components-togglebutton-primary-focus-box-shadow
--amplify-components-togglebutton-primary-focus-color
--amplify-components-togglebutton-primary-hover-background-color
--amplify-components-togglebutton-primary-hover-color
--amplify-components-togglebutton-primary-pressed-background-color
--amplify-components-togglebutton-primary-pressed-border-color
--amplify-components-togglebutton-primary-pressed-color
--amplify-components-togglebutton-primary-pressed-focus-background-color
--amplify-components-togglebutton-primary-pressed-focus-border-color
--amplify-components-togglebutton-primary-pressed-focus-color
--amplify-components-togglebutton-primary-pressed-hover-background-color
--amplify-components-togglebutton-primary-pressed-hover-border-color
--amplify-components-togglebutton-primary-pressed-hover-box-shadow
--amplify-components-togglebutton-primary-pressed-hover-color

Global styling

To override styling on all ToggleButtons, you can set the Amplify CSS variables or use the built-in .amplify-togglebutton class.

:root {
  --amplify-components-togglebutton-color: var(--amplify-colors-purple-60);
}

.amplify-togglebutton {
  color: var(--amplify-colors-purple-60);
}

<ToggleButton className="my-togglebutton-global">Press me!</ToggleButton>

Local styling

To override styling on a specific ToggleButton, you can use (in order of increasing specificity): a class selector, data attributes, or style props.

Using a class selector:

.my-togglebutton {
  border-radius: 20px;
}

<ToggleButton className="my-togglebutton">Press me!</ToggleButton>

Using data attributes:

.amplify-togglebutton[data-variation='primary'] {
  color: var(--amplify-colors-blue-60);
}

<ToggleButton className="my-togglebutton-data-attribute" variation="primary">
  'Press me!'
</ToggleButton>

Using style props:

import { Flex, ToggleButton, useTheme } from '@aws-amplify/ui-react';

export const ToggleButtonStylePropsExample = () => {
  const { tokens } = useTheme();
  return (
    <Flex>
      <ToggleButton color={tokens.colors.orange[60]}>Press me!</ToggleButton>
    </Flex>
  );
};