Path
Shows progress through an ordered workflow and lets users select a stage.
On this page
This docs is LLM-friendly and available as clean Markdown.
Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more
Usage
import {
GlPath,
GlPathItem,
GlPathItemMetric,
GlPathItemTitle,
} from "gitlab-ui-react/path";<GlPath>
<GlPathItem value="plan">
<GlPathItemTitle>Plan</GlPathItemTitle>
<GlPathItemMetric>2 days</GlPathItemMetric>
</GlPathItem>
</GlPath>Default
Use a path for a small set of ordered stages. Each item requires a unique value and one title; an optional metric can communicate age, duration, or another compact value.
Workflow path
import {
GlPath,
GlPathItem,
GlPathItemMetric,
GlPathItemTitle,
} from "gitlab-ui-react/path";
const stages = [
{ metric: "2d", title: "Plan", value: "plan" },
{ metric: "4d", title: "Develop", value: "develop" },
{ metric: "1d", title: "Review", value: "review" },
{ metric: "3d", title: "Deploy", value: "deploy" },
];
export default function PathExample() {
return (
<GlPath defaultValue="develop">
{stages.map((stage) => (
<GlPathItem key={stage.value} value={stage.value}>
<GlPathItemTitle>{stage.title}</GlPathItemTitle>
<GlPathItemMetric>{stage.metric}</GlPathItemMetric>
</GlPathItem>
))}
</GlPath>
);
}
Overflow
When the stages exceed the available width, Path keeps every item on one line and provides controls for horizontal scrolling.
Overflowing path
import {
GlPath,
GlPathItem,
GlPathItemMetric,
GlPathItemTitle,
} from "gitlab-ui-react/path";
const stages = [
{ metric: "1d", title: "Plan", value: "plan" },
{ metric: "2d", title: "Design", value: "design" },
{ metric: "4d", title: "Develop", value: "develop" },
{ metric: "1d", title: "Review", value: "review" },
{ metric: "2d", title: "Test", value: "test" },
{ metric: "3d", title: "Deploy", value: "deploy" },
];
export default function PathOverflowExample() {
return (
<div className="w-[18rem] max-w-full">
<GlPath defaultValue="develop">
{stages.map((stage) => (
<GlPathItem key={stage.value} value={stage.value}>
<GlPathItemTitle>{stage.title}</GlPathItemTitle>
<GlPathItemMetric>{stage.metric}</GlPathItemMetric>
</GlPathItem>
))}
</GlPath>
</div>
);
}
Accessibility
- Keep stage titles short and preserve their logical order.
- The selected stage is marked with
aria-current; update controlled state throughonValueChange. - Do not use a path as a generic breadcrumb or stepper when stages are not selectable workflow states.
- Localize
scrollLeftLabelandscrollRightLabelwhen the path can overflow.
API
GlPath
| Prop | Description | Default |
|---|---|---|
defaultValue |
Sets the initially selected item when uncontrolled. | First item |
value |
Controls the selected item value. | — |
onValueChange |
Reports selection requests. | — |
backgroundColor |
Sets the color beneath overflow fades. | "rgba(0,0,0,0)" |
scrollLeftLabel |
Labels the left overflow control. | "Scroll left" |
scrollRightLabel |
Labels the right overflow control. | "Scroll right" |
GlPathItem
| Prop | Description | Default |
|---|---|---|
value |
Provides a stable, unique selection value. | Required |
icon |
Adds a decorative GitLab icon before the title. | — |
disabled |
Prevents the item from being selected. | false |
children |
Requires one GlPathItemTitle and accepts one GlPathItemMetric. |
Required |
GlPathItemTitle
Accepts children and supported span attributes.
GlPathItemMetric
Accepts children and supported span attributes.