StepperField

StepperField allows users to increment or decrement a number input.

ARIA pattern Theme source React source Feedback

Demo

Usage

Import StepperField and styles. You could edit the stepping value directly but it will be validated and rounded to a valid one when the field loses focus.

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

export const DefaultStepperFieldExample = () => {
  return (
    <StepperField
      label="Stepper"
      defaultValue={0}
      min={0}
      max={10}
      step={1}
      labelHidden
    />
  );
};

Controlled component

To use the StepperField as a controlled component, use the value prop and onStepChange handler.

Note that onStepChange returns a new value (number), not the event object. This is because the StepperField is a complex component which is handling input, blur, and change events on the input element as well as click events on the button elements. The onStepChange handler simplifies all of this and returns the new value of the input in response to any of these events.

Controlled stepper

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

export const ControlledStepperFieldExample = () => {
  const [value, setValue] = React.useState<number>(0);

  const handleOnStepChange = (newValue: number) => {
    alert(`New value: ${newValue}`);
    setValue(newValue);
  };

  return (
    <StepperField
      label="Controlled stepper"
      value={value}
      onStepChange={handleOnStepChange}
    />
  );
};

Accessibility / Label behavior

Stepper

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

export const StepperFieldAccessibilityExample = () => {
  return (
    <StepperField label="Stepper" defaultValue={0} min={0} max={10} step={1} />
  );
};

Sizes

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

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

export const StepperFieldSizeExample = () => {
  return (
    <>
      <StepperField
        label="Stepper"
        defaultValue={0}
        min={0}
        max={10}
        step={1}
        size="small"
        labelHidden
      />
      <StepperField
        label="Stepper"
        defaultValue={0}
        min={0}
        max={10}
        step={1}
        labelHidden
      />
      <StepperField
        label="Stepper"
        defaultValue={0}
        min={0}
        max={10}
        step={1}
        size="large"
        labelHidden
      />
    </>
  );
};

State

The available StepperField states include isDisabled and isReadOnly. A disabled field will not be focusable or mutable and will not be submitted with form data. A read-only field cannot be edited by the user.

Disabled StepperField

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

export const DisabledStepperFieldExample = () => {
  return (
    <StepperField
      label="Stepper"
      defaultValue={0}
      min={0}
      max={10}
      step={1}
      labelHidden
      isDisabled
    />
  );
};

Read-only StepperField

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

export const ReadOnlyStepperFieldExample = () => {
  return (
    <StepperField
      label="Stepper"
      defaultValue={5}
      min={0}
      max={10}
      step={1}
      labelHidden
      isReadOnly
    />
  );
};

Validation error

Use the hasError and errorMessage props to mark a StepperField as having an validation error.

The is an error message.

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

export const StepperFieldValidationErrorExample = () => {
  return (
    <StepperField
      label="Stepper"
      defaultValue={0}
      min={0}
      max={10}
      step={1}
      errorMessage="The is an error message."
      hasError
      labelHidden
    />
  );
};

Standard HTML attributes

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

Stepper

<StepperField
  label="Stepper"
  min={0}
  max={10}
  step={1}
  name="stepper"
/>

Styling

Theme

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

StepperField Theme Source

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

const theme = {
  name: 'stepper-theme',
  tokens: {
    components: {
      stepperfield: {
        borderColor: { value: '{colors.secondary.20}' },
        input: {
          color: { value: '{colors.primary.80}' },
          fontSize: { value: '{fontSizes.large}' },
        },
        button: {
          color: { value: '{colors.primary.80}' },
          backgroundColor: { value: '{colors.neutral.20}' },
          _disabled: {
            color: { value: '{colors.primary.80}' },
          },
        },
      },
    },
  },
};

export const StepperFieldThemeExample = () => (
  <ThemeProvider theme={theme} colorMode="light">
    <StepperField
      label="Themed stepper"
      defaultValue={0}
      min={0}
      max={10}
      step={1}
      labelHidden
    />
  </ThemeProvider>
);

Icons

import { StepperField, IconsProvider } from '@aws-amplify/ui-react';
import { FiMinusSquare, FiPlusSquare } from 'react-icons/fi';

export const StepperFieldIconProviderExample = () => (
  <IconsProvider
    icons={{
      stepperField: {
        add: <FiPlusSquare />,
        remove: <FiMinusSquare />,
      },
    }}
  >
    <StepperField
      label="Themed stepper"
      defaultValue={0}
      min={0}
      max={10}
      step={1}
      labelHidden
    />
  </IconsProvider>
);

Target classes

Class	Description
`amplify-stepperfield`	Top level element that wraps the StepperField primitive
`amplify-stepperfield__button--decrease`	Class applied to the decrease button
`amplify-stepperfield__button--increase`	Class applied to the increase button
`amplify-stepperfield__input`	Class applied to the StepperField input

--amplify-components-stepperfield-border-color
--amplify-components-stepperfield-button-active-background-color
--amplify-components-stepperfield-button-active-color
--amplify-components-stepperfield-button-background-color
--amplify-components-stepperfield-button-color
--amplify-components-stepperfield-button-disabled-background-color
--amplify-components-stepperfield-button-disabled-color
--amplify-components-stepperfield-button-focus-background-color
--amplify-components-stepperfield-button-focus-color
--amplify-components-stepperfield-button-hover-background-color
--amplify-components-stepperfield-button-hover-color
--amplify-components-stepperfield-flex-direction
--amplify-components-stepperfield-input-color
--amplify-components-stepperfield-input-font-size
--amplify-components-stepperfield-input-text-align

Global styling

To override styling on all StepperFields, you can set the Amplify CSS variables or use the built-in .amplify-stepperfield, .amplify-stepperfield__input, amplify-stepperfield__button--decrease and amplify-stepperfield__button--increase class.

/* styles.css */
:root {
  --amplify-components-stepperfield-input-border-color: var(
    --amplify-colors-purple-80
  );
}
/* OR */
.amplify-stepperfield__input {
  border-color: var(--amplify-colors-purple-80);
}

Local styling

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

Using a class selector:

/* styles.css */
.custom-button .amplify-stepperfield__button--decrease,
.amplify-stepperfield__button--increase {
  color: var(--amplify-colors-white);
  background-color: var(--amplify-colors-purple-80);
}

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

import './styles.css';

<StepperField
  label="Stepper"
  classname="custom-button"
  defaultValue={0}
  min={0}
  max={10}
  step={1}
  labelHidden
/>;

Using data attributes:

/* styles.css */

/* Override only large size styles */
.amplify-stepperfield[data-size='large'] {
  width: 50%;
}

Using style props:

All style props will be applied to the Flex wrapper of the StepperField. To style the input of the StepperField, you can pass a inputStyles prop with the style props you want to apply to the input.

Stepper

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

export const StepperFieldStylePropsExample = () => {
  const { tokens } = useTheme();
  return (
    <>
      <StepperField
        label="Stepper"
        defaultValue={0}
        min={0}
        max={10}
        step={1}
        padding="large"
        border={`1px solid ${tokens.colors.primary[60]}`}
      />
      <StepperField
        label="Stepper"
        defaultValue={0}
        min={0}
        max={10}
        step={1}
        inputStyles={{
          backgroundColor: 'primary.10',
        }}
      />
    </>
  );
};