StepList

A StepList displays progress through a sequence of logical and numbered steps. It may also be used for navigation.

Uncontrolled Value

By default, the StepList component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultSelectedKey to set a value by default.

<StepList defaultSelectedKey='contacts'>
    <Item key='welcome'>Welcome</Item>
    <Item key='verify'>Verify Email</Item>
    <Item key='contacts'>Contacts</Item>
    <Item key='plan'>Select Plan</Item>
</StepList>

<StepList defaultSelectedKey='contacts'>
    <Item key='welcome'>Welcome</Item>
    <Item key='verify'>Verify Email</Item>
    <Item key='contacts'>Contacts</Item>
    <Item key='plan'>Select Plan</Item>
</StepList>

<StepList defaultSelectedKey="contacts">
  <Item key="welcome">
    Welcome
  </Item>
  <Item key="verify">
    Verify Email
  </Item>
  <Item key="contacts">
    Contacts
  </Item>
  <Item key="plan">
    Select Plan
  </Item>
</StepList>

Controlled Value

The StepList component can be used in a controlled manner. In the controlled variant you can pass in a selectedKey to controll the selected step.

function Example() {
  const [step, setStep] = useState('welcome');

  const steps = [
    { key: 'welcome', title: 'Welcome' },
    { key: 'verify', title: 'Verify Email' },
    { key: 'contacts', title: 'Contacts' },
    { key: 'plan', title: 'Select Plan' }
  ];

  return (
    <StepList items={steps} selectedKey={step} onSelectionChange={setStep}>
      {({ key, title, isValid }) => <Item key={key}>{title}</Item>}
    </StepList>
  );
}

function Example() {
  const [step, setStep] = useState('welcome');

  const steps = [
    { key: 'welcome', title: 'Welcome' },
    { key: 'verify', title: 'Verify Email' },
    { key: 'contacts', title: 'Contacts' },
    { key: 'plan', title: 'Select Plan' }
  ];

  return (
    <StepList
      items={steps}
      selectedKey={step}
      onSelectionChange={setStep}
    >
      {({ key, title, isValid }) => (
        <Item key={key}>{title}</Item>
      )}
    </StepList>
  );
}

function Example() {
  const [step, setStep] =
    useState('welcome');

  const steps = [
    {
      key: 'welcome',
      title: 'Welcome'
    },
    {
      key: 'verify',
      title:
        'Verify Email'
    },
    {
      key: 'contacts',
      title: 'Contacts'
    },
    {
      key: 'plan',
      title:
        'Select Plan'
    }
  ];

  return (
    <StepList
      items={steps}
      selectedKey={step}
      onSelectionChange={setStep}
    >
      {(
        {
          key,
          title,
          isValid
        }
      ) => (
        <Item key={key}>
          {title}
        </Item>
      )}
    </StepList>
  );
}

Wrapper

The StepList component supports wrappers for its items. So you can override any Step component prop or wrap it.

function Example() {
  const [step, setStep] = useState('verify');

  const steps = [
    { key: 'welcome', title: 'Welcome' },
    { key: 'verify', title: 'Verify Email' },
    { key: 'contacts', title: 'Contacts' },
    { key: 'plan', title: 'Select Plan' }
  ];

  return (
    <StepList items={steps} selectedKey={step} onSelectionChange={setStep}>
      {({ key, title, isValid }) => (
        <Item key={key}>
          {(props) => (
            <TooltipTrigger placement="bottom">
              <Step {...props} />
              <Tooltip>{title}</Tooltip>
            </TooltipTrigger>
          )}
        </Item>
      )}
    </StepList>
  );
}

function Example() {
  const [step, setStep] = useState('verify');

  const steps = [
    { key: 'welcome', title: 'Welcome' },
    { key: 'verify', title: 'Verify Email' },
    { key: 'contacts', title: 'Contacts' },
    { key: 'plan', title: 'Select Plan' }
  ];

  return (
    <StepList
      items={steps}
      selectedKey={step}
      onSelectionChange={setStep}
    >
      {({ key, title, isValid }) => (
        <Item key={key}>
          {(props) => (
            <TooltipTrigger placement="bottom">
              <Step {...props} />
              <Tooltip>{title}</Tooltip>
            </TooltipTrigger>
          )}
        </Item>
      )}
    </StepList>
  );
}

function Example() {
  const [step, setStep] =
    useState('verify');

  const steps = [
    {
      key: 'welcome',
      title: 'Welcome'
    },
    {
      key: 'verify',
      title:
        'Verify Email'
    },
    {
      key: 'contacts',
      title: 'Contacts'
    },
    {
      key: 'plan',
      title:
        'Select Plan'
    }
  ];

  return (
    <StepList
      items={steps}
      selectedKey={step}
      onSelectionChange={setStep}
    >
      {(
        {
          key,
          title,
          isValid
        }
      ) => (
        <Item key={key}>
          {(props) => (
            <TooltipTrigger placement="bottom">
              <Step
                {...props}
              />
              <Tooltip>
                {title}
              </Tooltip>
            </TooltipTrigger>
          )}
        </Item>
      )}
    </StepList>
  );
}

Sizes

The StepList component supports different sizes.

function Example() {
    return ['small', 'medium', 'large'].map((size) => 
        (<StepList size={size} key={size}>
            <Item key='welcome'>Welcome</Item>
            <Item key='verify'>Verify Email</Item>
            <Item key='contacts'>Contacts</Item>
            <Item key='plan'>Select Plan</Item>
         </StepList>))
}

function Example() {
    return ['small', 'medium', 'large'].map((size) => 
        (<StepList size={size} key={size}>
            <Item key='welcome'>Welcome</Item>
            <Item key='verify'>Verify Email</Item>
            <Item key='contacts'>Contacts</Item>
            <Item key='plan'>Select Plan</Item>
         </StepList>))
}

function Example() {
  return [
    'small',
    'medium',
    'large'
  ].map((size) => (
    <StepList
      size={size}
      key={size}
    >
      <Item key="welcome">
        Welcome
      </Item>
      <Item key="verify">
        Verify Email
      </Item>
      <Item key="contacts">
        Contacts
      </Item>
      <Item key="plan">
        Select Plan
      </Item>
    </StepList>
  ));
}

Disabled Keys

The StepList allows you to disable certain keys.

<StepList disabledKeys={['verify', 'contacts']}>
    <Item key='welcome'>Welcome</Item>
    <Item key='verify'>Verify Email</Item>
    <Item key='contacts'>Contacts</Item>
    <Item key='plan'>Select Plan</Item>
</StepList>

<StepList disabledKeys={['verify', 'contacts']}>
    <Item key='welcome'>Welcome</Item>
    <Item key='verify'>Verify Email</Item>
    <Item key='contacts'>Contacts</Item>
    <Item key='plan'>Select Plan</Item>
</StepList>

<StepList
  disabledKeys={[
    'verify',
    'contacts'
  ]}
>
  <Item key="welcome">
    Welcome
  </Item>
  <Item key="verify">
    Verify Email
  </Item>
  <Item key="contacts">
    Contacts
  </Item>
  <Item key="plan">
    Select Plan
  </Item>
</StepList>

Invalid steps

The StepList allows you to mark a step as invalid. It's useful when there is a need to represent a non-visible failed step.

<StepList defaultSelectedKey="verify" disabledKeys={['contacts', 'plan']}>
  <Item key="welcome">Welcome</Item>
  <Item key="verify" isValid={false}>Verify Email</Item>
  <Item key="contacts">Contacts</Item>
  <Item key="plan">Select Plan</Item>
</StepList>

<StepList
  defaultSelectedKey="verify"
  disabledKeys={['contacts', 'plan']}
>
  <Item key="welcome">Welcome</Item>
  <Item key="verify" isValid={false}>Verify Email</Item>
  <Item key="contacts">Contacts</Item>
  <Item key="plan">Select Plan</Item>
</StepList>

<StepList
  defaultSelectedKey="verify"
  disabledKeys={[
    'contacts',
    'plan'
  ]}
>
  <Item key="welcome">
    Welcome
  </Item>
  <Item
    key="verify"
    isValid={false}
  >
    Verify Email
  </Item>
  <Item key="contacts">
    Contacts
  </Item>
  <Item key="plan">
    Select Plan
  </Item>
</StepList>

Step

You might want to re-use the Step component implementation as well as override its' props in the StepList. It supports different states and color variants.

<ol style={{counterReset: 'step', width: 'fit-content'}}>
    <Step size='small'>One</Step>
    <Step iconName='ChevronRightIcon' iconVariant='outline'>Two</Step>
    <Step isDisabled>Three</Step>
    <Step isSelected>Four</Step>
    <Step isValid={false}>Five</Step>
    <Step color='primary'>Six</Step>
    <Step color='secondary'>Seven</Step>
    <Step size='large' style={{width: 'fit-content'}}/>
</ol>

<ol
  style={{ counterReset: 'step', width: 'fit-content' }}
>
  <Step size="small">One</Step>
  <Step iconName="ChevronRightIcon" iconVariant="outline">
    Two
  </Step>
  <Step isDisabled>Three</Step>
  <Step isSelected>Four</Step>
  <Step isValid={false}>Five</Step>
  <Step color="primary">Six</Step>
  <Step color="secondary">Seven</Step>
  <Step size="large" style={{ width: 'fit-content' }} />
</ol>

<ol
  style={{
    counterReset:
      'step',
    width:
      'fit-content'
  }}
>
  <Step size="small">
    One
  </Step>
  <Step
    iconName="ChevronRightIcon"
    iconVariant="outline"
  >
    Two
  </Step>
  <Step isDisabled>
    Three
  </Step>
  <Step isSelected>
    Four
  </Step>
  <Step
    isValid={false}
  >
    Five
  </Step>
  <Step color="primary">
    Six
  </Step>
  <Step color="secondary">
    Seven
  </Step>
  <Step
    size="large"
    style={{
      width:
        'fit-content'
    }}
  />
</ol>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API