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> ); };