SwitchField

SwitchField allows users to toggle an input.

ARIA pattern Theme source React source Feedback

Demo

Usage

The most basic usage simply includes a SwitchField component passing in a required label prop.

This is a switch

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

export const DefaultSwitchFieldExample = () => {
  return <SwitchField label="This is a switch" />;
};

Accessibility / Label behavior

Controlled component

The SwitchFIeld can be a controlled component by passing in the controlled boolean value as the isChecked prop. To allow the user to toggle a controlled SwitchField, the onChange handler must be passed in and update the controlled value. An example of this pattern is displayed below.

This is a switch

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

export const SwitchFieldIsCheckedExample = () => {
  const [isChecked, setIsChecked] = React.useState(true);

  return (
    <>
      <SwitchField
        label="This is a switch"
        isChecked={isChecked}
        onChange={(e) => {
          setIsChecked(e.target.checked);
        }}
      />
      <Button
        onClick={() => {
          setIsChecked((isChecked) => !isChecked);
        }}
      >
        Switch
      </Button>
    </>
  );
};

defaultChecked

The defaultChecked property is a boolean value and will define the starting value for an uncontrolled switchField.

This is a switch

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

export const SwitchFieldDefaultCheckedExample = () => {
  return <SwitchField label="This is a switch" defaultChecked={true} />;
};

thumbColor

The thumbColor property is a CSS color value and will define the color of the thumb in the switchField.

This is a switch

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

export const SwitchFieldThumbColorExample = () => {
  const { tokens } = useTheme();
  return (
    <SwitchField
      label="This is a switch"
      thumbColor={tokens.colors.orange[10]}
    />
  );
};

trackColor

The trackColor property is a CSS color value that will define the color of the track of the switchField while in the off position.

This is a switch

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

export const SwitchFieldTrackColorExample = () => {
  const { tokens } = useTheme();
  return (
    <SwitchField label="This is a switch" trackColor={tokens.colors.blue[60]} />
  );
};

trackCheckedColor

The trackCheckedColor property is a CSS color value that will define the color of the track of the switchField while in the on position.

This is a switch

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

export const SwitchFieldTrackCheckedColorExample = () => {
  const { tokens } = useTheme();
  return (
    <SwitchField
      label="This is a switch"
      trackCheckedColor={tokens.colors.green[60]}
      defaultChecked={true}
    />
  );
};

isDisabled

The isDisabled property is a boolean value that when set to true will disable the switchField from being toggled.

This is a switch

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

export const DisabledSwitchFieldExample = () => {
  return <SwitchField label="This is a switch" isDisabled={true} />;
};

name

The name property is a string that defines the name of the field that will be submitted with the form as a name/value pair.

This is a switch

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

export const SwitchFieldNameExample = () => {
  return <SwitchField label="This is a switch" name="switchName" />;
};

size

The size property is an enum value that modifies the size of the switchField component. The available sizes are small, (default), and large.

This is a small switch

This is a switch

This is a large switch

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

export const SwitchFieldSizeExample = () => {
  return (
    <>
      <SwitchField label="This is a small switch" size="small" />
      <SwitchField label="This is a switch" />
      <SwitchField label="This is a large switch" size="large" />
    </>
  );
};

label

The label property is a required string or ReactNode that will display next to the switchField component and wrapped in an html label tag.

This is a switch

This is a JSX label

import { SwitchField, View } from '@aws-amplify/ui-react';

export const SwitchFieldLabelExample = () => {
  return (
    <>
      <SwitchField label="This is a switch" />
      <SwitchField label={<View as="span">This is a JSX label</View>} />
    </>
  );
};

labelPosition

The labelPosition property is an enum value that defines the label's position in relation to the switchField. Available values are start, end, top, and bottom.

This is a switch

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

export const SwitchFieldLabelPositionExample = () => {
  return (
    <>
      <SwitchField label="This is a switch" labelPosition="start" />
      <SwitchField label="This is a switch" labelPosition="end" />
      <SwitchField label="This is a switch" labelPosition="top" />
      <SwitchField label="This is a switch" labelPosition="bottom" />
    </>
  );
};

isLabelHidden

The isLabelHidden property is a boolean value that will visually hide the label.

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

export const SwitchFieldLabelHiddenExample = () => {
  return (
    <SwitchField label="This is a visually hidden label" isLabelHidden={true} />
  );
};

value

The value property is a string value that defines the value of the field that will be submitted with the form as a name/value pair.

This is a switch

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

export const SwitchFieldValueExample = () => {
  return <SwitchField label="This is a switch" value="Switch Form Value" />;
};

onChange

The onChange property is a callback function that will be called with a change event to the switchField.

This is a switch

Number of times the switch has changed 0

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

export const SwitchFieldOnChangeExample = () => {
  const [switchCount, setSwitchCount] = React.useState(0);
  const changeCount = () => {
    setSwitchCount(switchCount + 1);
  };
  return (
    <>
      <SwitchField label="This is a switch" onChange={changeCount} />
      <Text>Number of times the switch has changed {switchCount}</Text>
    </>
  );
};

Error state

import { SwitchField, Button, Flex } from '@aws-amplify/ui-react';
import * as React from 'react';

export const SwitchFieldErrorExample = () => {
  const [isChecked, setIsChecked] = React.useState(false);
  const [hasError, setHasError] = React.useState(false);
  const onSubmit = (event) => {
    event.preventDefault();
    if (!isChecked) {
      setHasError(true);
    } else {
      setHasError(false);
      alert(`success`);
    }
  };

  return (
    <Flex
      as="form"
      direction="column"
      alignItems="flex-start"
      onSubmit={onSubmit}
    >
      <SwitchField
        label="I agree to the terms and conditions"
        labelPosition="end"
        isChecked={isChecked}
        hasError={hasError}
        errorMessage="Please agree to the terms and conditions"
        onChange={(e) => {
          setIsChecked(e.target.checked);
        }}
      />
      <Button type="submit">Submit</Button>
    </Flex>
  );
};

CSS Styling

Theme

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

SwitchField Theme Source

Themed Switch

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

const theme: Theme = {
  name: 'switchfield-theme',
  tokens: {
    components: {
      switchfield: {
        thumb: {
          backgroundColor: { value: '{colors.background.primary}' },
          borderColor: { value: '{colors.border.primary}' },
          transition: {
            duration: { value: '{time.long}' },
          },
        },

        track: {
          backgroundColor: { value: '{colors.background.tertiary}' },
          checked: {
            backgroundColor: { value: '{colors.secondary.60}' },
          },
          transition: {
            duration: { value: '{time.long}' },
          },
        },
      },
    },
  },
};

export const SwitchFieldThemeExample = () => (
  <ThemeProvider theme={theme} colorMode="light">
    <SwitchField label="Themed Switch" />
  </ThemeProvider>
);

Target classes

Class	Description
`amplify-switchfield`	Top level element that wraps the SwitchField primitive
`amplify-switch__label`	Class applied to the SwitchField label text
`amplify-switch__thumb`	Class applied to the SwitchField thumb
`amplify-switch__track`	Class applied to the SwitchField track
`amplify-switch__wrapper`	Class applied to the label element that wraps the SwitchField label and track

--amplify-components-switchfield-disabled-opacity
--amplify-components-switchfield-focused-shadow
--amplify-components-switchfield-font-size
--amplify-components-switchfield-label-padding
--amplify-components-switchfield-large-font-size
--amplify-components-switchfield-small-font-size
--amplify-components-switchfield-thumb-background-color
--amplify-components-switchfield-thumb-border-color
--amplify-components-switchfield-thumb-border-radius
--amplify-components-switchfield-thumb-border-style
--amplify-components-switchfield-thumb-border-width
--amplify-components-switchfield-thumb-checked-transform
--amplify-components-switchfield-thumb-transition-duration
--amplify-components-switchfield-thumb-width
--amplify-components-switchfield-track-background-color
--amplify-components-switchfield-track-border-radius
--amplify-components-switchfield-track-checked-background-color
--amplify-components-switchfield-track-error-background-color
--amplify-components-switchfield-track-height
--amplify-components-switchfield-track-padding
--amplify-components-switchfield-track-transition-duration
--amplify-components-switchfield-track-width

Global Styling

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

This is a switch

/* styles.css */
:root {
  --amplify-components-switchfield-default-font-size: 0.5rem;
}
/* OR */
.amplify-switchfield {
  font-size: 0.5rem;
}

Local styling

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

Using a class selector:

This is a switch

/* styles.css */
.my-custom-switchfield {
  font-size: 0.75rem;
}

import './styles.css';

<SwitchField label="This is a switch" className="my-custom-switchfield" />;

Using data attributes:

large switchfield

/* styles.css */
/* Override only large size styles */
.amplify-switchfield[data-size='large'] {
  font-size: 2.5rem;
}

import './styles.css';

<SwitchField label="large switchfield" size="large" />;

Using style props:

This is a switch

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

export const SwitchFieldStylePropsExample = () => {
  return <SwitchField label="This is a switch" fontSize="xs" />;
};