Multi Step Nav

View in Lexicon

A multi step nav, also known as a wizard, is a determinate progress bar used in long processes that divides the main task into subtasks. The wizard lets the user quickly identify their current progress in completing the task and navigate forwards and backwards between steps if needed.

install	yarn add @clayui/multi-step-nav
version
use	`import MultiStepNav from '@clayui/multi-step-nav';`

Table of Contents

Center
State
Indicator position
Collapsable Steps
API Reference

It’s used when a major or big task has to be divided into smaller task, with the aim of letting the user breath in the process and providing them with a sense of progression.

Each step can have two different states: active or complete defined by props as you can see below.

Open Sandbox

import {Provider} from '@clayui/core';
import MultiStepNav from '@clayui/multi-step-nav';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(1);

	const steps = [
		{
			subTitle: 'SubOne',
			title: 'One',
		},
		{
			subTitle: 'SubTwo',
			title: 'Two',
		},
		{
			subTitle: 'SubThree',
			title: 'Three',
		},
		{
			subTitle: 'SubFour',
			title: 'Four',
		},
	];

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<MultiStepNav>
					{steps.map(({subTitle, title}, i) => {
						const complete = value > i;

						return (
							<MultiStepNav.Item
								active={value === i}
								expand={i + 1 !== steps.length}
								key={i}
								state={complete ? 'complete' : undefined}
							>
								<MultiStepNav.Title>{title}</MultiStepNav.Title>
								<MultiStepNav.Divider />
								<MultiStepNav.Indicator
									complete={complete}
									label={1 + i}
									onClick={() => setValue(i)}
									subTitle={subTitle}
								/>
							</MultiStepNav.Item>
						);
					})}
				</MultiStepNav>
			</div>
		</Provider>
	);
}

Center

The center boolean property centers the multi-step-nav.

Open Sandbox

import {Provider} from '@clayui/core';
import MultiStepNav from '@clayui/multi-step-nav';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(1);

	const steps = [
		{
			subTitle: 'Step 01',
			title: 'Ticket Buyer Information',
		},
		{
			subTitle: 'Step 02',
			title: 'Attendee Information',
		},
		{
			subTitle: 'Step 03',
			title: 'Payment Information',
		},
		{
			subTitle: 'Step 04',
			title: 'Completed',
		},
	];

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<MultiStepNav center>
					{steps.map(({subTitle, title}, i) => {
						const complete = value > i;

						return (
							<MultiStepNav.Item
								active={value === i}
								expand={i + 1 !== steps.length}
								key={i}
								state={complete ? 'complete' : undefined}
							>
								<MultiStepNav.Title>{title}</MultiStepNav.Title>
								<MultiStepNav.Divider />
								<MultiStepNav.Indicator
									complete={complete}
									label={1 + i}
									onClick={() => setValue(i)}
									subTitle={subTitle}
								/>
							</MultiStepNav.Item>
						);
					})}
				</MultiStepNav>
			</div>
		</Provider>
	);
}

State

Each step can have two different states: active or complete defined by props as you can see below.

The active state can be set using the active property in the ClayMultiStepNav.Item or ClayMultiStepNavWithBasicItems component which defines the step index.

The complete and error states are defined using the state property in the ClayMultiStepNav.Item which defines whether the item is complete or has an error in the current state. The ClayMultiStepNavWithBasicItems component follows the same API with the difference that it sets the state of the item to the current step which is set when using the active or defaultActive API.

Open Sandbox

import {Provider} from '@clayui/core';
import {ClayMultiStepNavWithBasicItems} from '@clayui/multi-step-nav';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(1);

	const steps = [
		{
			subTitle: 'SubOne',
			title: 'One',
		},
		{
			subTitle: 'SubTwo',
			title: 'Two',
		},
		{
			subTitle: 'SubThree',
			title: 'Three',
		},
		{
			subTitle: 'SubFour',
			title: 'Four',
		},
	];

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<ClayMultiStepNavWithBasicItems
					active={value}
					onActiveChange={setValue}
					state="error"
					steps={steps}
				/>
			</div>
		</Provider>
	);
}

Indicator position

Some use cases don’t need the title or subtitle to add context to the steps, in those cases you might just want the label to be rendered to the top of the indicator, so it can truncate the text if it is long.

<ClayMultiStepNav indicatorLabel="top">
	<ClayMultiStepNav.Item
		active={active}
		complete={complete}
		expand={i + 1 !== steps.length}
		key={i}
	>
		<ClayMultiStepNav.Divider />
		<ClayMultiStepNav.Indicator
			complete={complete}
			label={1 + i}
			onClick={onClick}
			subTitle={label}
		/>
	</ClayMultiStepNav.Item>
</ClayMultiStepNav>

Collapsable Steps

Using ClayMultiStepNavWithBasicItems in combination with maxStepsShown prop you can collapse the steps that don’t fit into a dropdown to ensure good user experience.

Open Sandbox

import {Provider} from '@clayui/core';
import {ClayMultiStepNavWithBasicItems} from '@clayui/multi-step-nav';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [value, setValue] = useState(1);

	const steps = [
		{
			subTitle: 'SubOne',
			title: 'One',
		},
		{
			subTitle: 'SubTwo',
			title: 'Two',
		},
		{
			subTitle: 'SubThree',
			title: 'Three',
		},
		{
			subTitle: 'SubFour',
			title: 'Four',
		},
	];

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<ClayMultiStepNavWithBasicItems
					active={value}
					maxStepsShown={2}
					onActiveChange={setValue}
					steps={steps}
				/>
			</div>
		</Provider>
	);
}

API Reference

MultiStepNav

typeof MultiStepNav

Parameters

Properties

autoCollapse

boolean | undefined= true

Flag to indicate if nav should add multi-step-nav-collapse-sm class

center

boolean | undefined

Flag to indicate if nav should add the multi-step-nav-center class.

fixedWidth

boolean | undefined

Flag to indicate if nav should add multi-step-item-fixed-width class.

indicatorLabel

"bottom" | "top" | undefined= "bottom"

Flag to indicate the position of the indicator label.

Returns

Element

MultiStepNavWithBasicItems

({ active, activeIndex, defaultActive, maxStepsShown, onActiveChange, onIndexChange, spritemap, state, steps, ...otherProps }: IProps) => JSX.Element

Parameters

Properties

active

number | undefined

Value for which step index is active (controlled).

activeIndex

number | undefined

Value for which step index is active

defaultActive

number | undefined

Set the default value of active state (uncontrolled).

maxStepsShown

number | undefined= 7

Determines at what point a dropdown is show. The dropdown will always show as the 2nd to last step.

onActiveChange

InternalDispatch<number> | undefined

Callback for when step is clicked

onIndexChange

InternalDispatch<number> | undefined

Callback for when step is clicked

spritemap

string | undefined

Path to spritemap for icon symbol.

state

"error" | "complete" | undefined= "complete"

Defines the status of the current step.

steps *

Array<ISteps>

List of steps to display

autoCollapse

boolean | undefined

Flag to indicate if nav should add multi-step-nav-collapse-sm class

center

boolean | undefined

Flag to indicate if nav should add the multi-step-nav-center class.

fixedWidth

boolean | undefined

Flag to indicate if nav should add multi-step-item-fixed-width class.

indicatorLabel

"bottom" | "top" | undefined

Flag to indicate the position of the indicator label.

Returns

Element

Item

({ active, children, className, complete, expand, state, ...otherProps }: IProps) => JSX.Element

Parameters

active

boolean | undefined

Flag to indicate if active classname should be applied

className

string | undefined

Additional className to apply

complete

boolean | undefined

Flag to indicate if complete classname should be applied

expand

boolean | undefined

Flag to indicate if progress line should expand out from step

state

State | undefined

Defines the status of the step.

Returns

Element

Title

({ children }: Props) => JSX.Element

Parameters

Properties

children

React.ReactNode

Title content.

Returns

Element

Edit this page on GitHub

Contributors

Matuzalém Teles, Bryce Osterhaus, Krešimir Čoko, Diego Nascimento, Patrick Yeo

Last edited January 29, 2025 at 1:35:04 AM

Table of Contents

Center
State
Indicator position
Collapsable Steps
API Reference