Skip to main content
Numbered lists and the <Steps> component both show a sequence, but they set different expectations. Use <Steps> when the reader performs a sequence and each action needs explanation. Use a numbered list when the sequence is simple or describes what the system does.

​
When to use the steps component

Use <Steps> when:
  • Each step needs substeps, decisions, or more context than a single list item can hold.
  • The steps are sequential. For example, completing step 2 requires completing step 1 first.
Example steps
The title of each step describes what the user accomplishes. If someone only reads the step titles, and not the content of every step, they should be able to understand the overall procedure. Don’t use vague titles like “Step 2” or “Installation.” And don’t just describe what happens mechanically in a step title, like “Click Enable.”

​
When a numbered list is better

Use a numbered list when:
  • Each item fits in one or two lines.
  • You’re listing things in a logical order, not guiding someone through a task.
  • The content doesn’t need sub-elements like code blocks, images, or multiple lines of context.
Example descriptive numbered list
This is a sequence of things that happen, not a sequence of things the user does. Using a <Steps> component doesn’t help communicate the sequence.
Example procedural numbered list
This is a simple process that doesn’t require any decisions or complex actions. A numbered list is a good fit.

​
The one-line step problem

A common misuse of the steps component is wrapping content without using the component’s full capabilities.
These one-liners mostly just add whitespace. A numbered list would communicate the same thing.
Better as a numbered list
If your steps have no child content—no code blocks, prose, or decisions—they can probably be list items instead.

​
Step titles matter

Step titles appear in the table of contents on some Mintlify themes and readers scan them to understand the overall procedure. A title like “Configure” is less helpful than “Configure your webhook endpoint.” The latter tells you exactly what the step is about. Generally, start step titles with a verb and end with the specific thing being acted on.
  • “Installation” → “Install project dependencies”
  • “Analytics script” → “Add the analytics script to your layout”
  • “Test” → “Test the connection”
Next up: Describe branching procedures — How to handle when a procedure forks based on platform, role, preference, or other factors.