Skip to content



Wizard is a component that guides users through a series of predefined steps to complete a larger task. It simplifies complex tasks by breaking them down into manageable steps, reducing the perceived complexity.

When to use wizard

  • Use a wizard when dealing with large tasks that cannot be simplified. Breaking them down into steps helps users focus on each part of the task.
  • If a task requires a specific sequence of steps to be followed, a wizard ensures users don't miss important parts and make fewer mistakes.
  • Wizards are suitable when a task involves three-five steps. For smaller tasks with just two steps or very large tasks with more than ten steps, consider alternative approaches and components.

When don’t use wizard

  • Avoid using wizards for educational purposes, as they focus on task completion rather than providing additional information for learning. Instead, use components like FeaturePopover, Info icons, hint links, or videos for education.
  • Advanced users may find predefined steps in a wizard restrictive. Consider using wizards for audiences that would benefit from step-by-step guidance.

Component composition

Component consists of the following:

  • Wizard.Sidebar
  • Wizard.Stepper
  • Wizard.Content
  • Wizard.Step
Wizard sidebar styles
Appearance example
Sidebar stylesmax-width: 220px; padding: 40px 8px; color: var(--white); background-color: var(--violet-600); font-size: var(--fs-300); line-height: var(--lh-300); font-weight: 700;
Step styles20px * 24px
Stepper stylespadding: 8px 12px; color: var(--white); font-size: var(--fs-200); line-height: var(--lh-200); font-weight: 700; If a stepper has optional text or a sub-step, they have the following styles: margin-top: 4px; color: color-mod(var(--white) a(75%)); font-size: var(--fs-100); line-height: var(--lh-100); font-weight: 400;

Stepper states

Stepper states
StateAppearance exampleStyles
Normalbackground-color: var(--control-primary-advertising), border-radius: var(--rounded-medium)
Hoverbackground-color: var(--control-primary-advertising-hover), cursor: pointer
Activebackground-color: var(--control-primary-advertising-active)
Disabled Use --disabled-opacity token. When hovering on a button in this state, display a tooltip with a description of why the step is disabled.
checkedThe number changes to a Check icon in size M.

Content area styles

Wizard content area styles
Appearance example
Content area paddingspadding: 40px; background-color: var(--white); color: var(--gray-800); font-size: var(--fs-200); line-height: var(--lh-200); font-weight: 400;
Header stylesmargin-bottom: 20px; color: var(--gray-800); font-size: var(--fs-500); line-height: var(--lh-500); font-weight: 700;
Icon for closing windowThe Close icon uses L size, and --icon-secondary-neutral token for color. On hover, the color of the icon changes to the darker one using CSS filter.
Footer stylesFor basic controls use L size. margin-bottom: 20px; color: var(--gray-800); font-size: var(--fs-500); line-height: var(--lh-500);

Keyboard control

  • When opening a Wizard, the focus should move to it.
  • Users can move between interactive elements within the window using the Tab key.
  • The window can be closed with the Esc key.

When the fullscreen modal closes, the focus should return to the page. Refer to Accessibility guidelines.

Wizard in Modal

For the Wizard displayed in a Modal, ensure the following styles:

max-width: 980px;
max-height: 700px;
max-width: 980px;
max-height: 700px;

Collapsing panel with steps on screen less than 1060px

Collapse the panel to 44px, leaving only the step numbers. On hover per step, show the name of the step.


The scroll behavior inside and outside the window, the general rules for content, etc. are the same as for the Modal component.

Center the Wizard relative to the user's viewport. And leave margins of 40px outside the window.

Usage in UX/UI


For consistent user experience within products of the same platform, use a Wizard for setting up products.

In exceptional cases, steps can be placed in the content area of the page.

Here are some scenarios where a universal solution is recommended:

Form validation

After submitting a form, highlight all invalid inputs and focus on the first invalid input.

For more information about validation, refer to the Validation.

Form loading error

If an error occurs on the backend while submitting a form, display the error message above the form.

Sizes of controls in the form

In the form, use the same sizes for inputs and controls.

Saving the entered value

If data entered into the form by the user was not sent and the window is closed, save the entered data so that the user doesn't lose it.

Released under the MIT License.

Released under the MIT License.