---
title: "MazTimeline"
description: "MazTimeline is a step/progress timeline component for Vue 3 with support for horizontal, vertical, and responsive layouts, customizable colors, sizes, step states, and scoped slots"
package: "maz-ui"
url: "https://maz-ui.com/components/maz-timeline"
---

# MazTimeline

> MazTimeline is a step/progress timeline component for Vue 3 with support for horizontal, vertical, and responsive layouts, customizable colors, sizes, step states, and scoped slots

- Package: `maz-ui`
- Import: `import MazTimeline from 'maz-ui/components/MazTimeline'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-timeline

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

---

Control the current step:

## Basic usage

```vue
<template>
  <MazTimeline v-model="currentStep" :steps="steps" />
</template>

<script lang="ts" setup>
  import { ref } from 'vue'
  import MazTimeline from 'maz-ui/components/MazTimeline'

  const currentStep = ref(1)
  const steps = [
    { title: 'Account', subtitle: 'Create your account' },
    { title: 'Profile', subtitle: 'Set up your profile' },
    { title: 'Settings', subtitle: 'Configure preferences' },
    { title: 'Complete', subtitle: 'All done!' },
  ]
</script>
```

## Directions

### Horizontal

```vue
<template>
  <MazTimeline v-model="currentStep" :steps="steps" direction="horizontal" />
</template>
```

### Vertical

```vue
<template>
  <MazTimeline v-model="currentStep" :steps="steps" direction="vertical" />
</template>
```

### Auto (responsive)

The default direction is `'auto'`, which switches from horizontal to vertical based on the `breakpoint` prop (default: `'768px'`).

```vue
<template>
  <MazTimeline
    v-model="currentStep"
    :steps="steps"
    direction="auto"
    breakpoint="768px"
  />
</template>
```

## Colors

Use the `color` prop to change the theme color.

```vue
<template>
  <MazTimeline :steps="steps" color="primary" />
  <MazTimeline :steps="steps" color="secondary" />
  <MazTimeline :steps="steps" color="info" />
  <MazTimeline :steps="steps" color="success" />
  <MazTimeline :steps="steps" color="warning" />
  <MazTimeline :steps="steps" color="destructive" />
</template>
```

## Sizes

Use the `size` prop to change the indicator size.

```vue
<template>
  <MazTimeline :steps="steps" size="mini" />
  <MazTimeline :steps="steps" size="xs" />
  <MazTimeline :steps="steps" size="sm" />
  <MazTimeline :steps="steps" size="md" />
  <MazTimeline :steps="steps" size="lg" />
  <MazTimeline :steps="steps" size="xl" />
</template>
```

## Step states

Each step can have a manual `state` property: `'completed'`, `'active'`, `'error'`, `'warning'`, or `'pending'`.

```vue
<template>
  <MazTimeline :steps="stateSteps" direction="horizontal" />
</template>

<script lang="ts" setup>
  const stateSteps = [
    { title: 'Completed', subtitle: 'Step finished', state: 'completed' },
    { title: 'Active', subtitle: 'In progress', state: 'active' },
    { title: 'Error', subtitle: 'Something went wrong', state: 'error' },
    { title: 'Warning', subtitle: 'Needs attention', state: 'warning' },
    { title: 'Pending', subtitle: 'Not started', state: 'pending' },
  ]
</script>
```

## Clickable

Enable `clickable` to allow users to navigate between steps by clicking on them. The `click-step` event is emitted with the step index.

```vue
<template>
  <MazTimeline v-model="clickableStep" :steps="steps" clickable />
</template>

<script lang="ts" setup>
  import { ref } from 'vue'

  const clickableStep = ref(0)
</script>
```

## Disabled steps

Individual steps can be disabled by setting `disabled: true` on the step object.

```vue
<template>
  <MazTimeline v-model="currentStep" :steps="disabledSteps" clickable />
</template>

<script lang="ts" setup>
  const disabledSteps = [
    { title: 'Account', subtitle: 'Create your account' },
    { title: 'Profile', subtitle: 'Set up your profile' },
    { title: 'Settings', subtitle: 'Locked', disabled: true },
    { title: 'Complete', subtitle: 'All done!' },
  ]
</script>
```

## Without step numbers

Hide the step numbers inside indicators with `:show-step-numbers="false"`.

```vue
<template>
  <MazTimeline
    v-model="currentStep"
    :steps="steps"
    :show-step-numbers="false"
  />
</template>
```

## Without auto-validate

By default, completed steps show a checkmark. Disable this with `:auto-validate-steps="false"`.

```vue
<template>
  <MazTimeline
    :model-value="2"
    :steps="steps"
    :auto-validate-steps="false"
  />
</template>
```

## Rounded sizes

Customize the indicator border radius with the `rounded-size` prop.

```vue
<template>
  <MazTimeline :steps="steps" rounded-size="full" />
  <MazTimeline :steps="steps" rounded-size="lg" />
  <MazTimeline :steps="steps" rounded-size="md" />
  <MazTimeline :steps="steps" rounded-size="sm" />
  <MazTimeline :steps="steps" rounded-size="none" />
</template>
```

## Custom Icons

```vue
<template>
  <MazTimeline
    v-model="currentStep"
    :steps="steps"
    size="lg"
  />
</template>

<script lang="ts" setup>
  import { MazCommandLine } from '@maz-ui/icons/MazCommandLine'
  import { MazClipboardDocumentList } from '@maz-ui/icons/MazClipboardDocumentList'
  import { MazClipboardDocumentCheck } from '@maz-ui/icons/MazClipboardDocumentCheck'
  import { MazComputerDesktop } from '@maz-ui/icons/MazComputerDesktop'

  const iconsSteps = [
    { title: 'PO', subtitle: 'Writing PRD', icon: MazClipboardDocumentList },
    { title: 'Dev', subtitle: 'Building Code', icon: MazCommandLine },
    { title: 'Tech Lead', subtitle: 'Review Code', icon: MazComputerDesktop },
    { title: 'QA', subtitle: 'Testing', icon: MazClipboardDocumentCheck },
  ]
</script>
```

## Custom slots

MazTimeline provides scoped slots for full customization.

### Indicator slot

```vue
<template>
  <MazTimeline v-model="currentStep" :steps="steps">
    <template #indicator="{ step, index, state }">
      <span style="font-size: 1.2em">{{ index + 1 }}.</span>
    </template>
  </MazTimeline>
</template>
```

### Content slot

```vue
<template>
  <MazTimeline v-model="currentStep" :steps="steps">
    <template #content="{ step, index, state }">
      <div class="text-center">
        <strong>{{ step.title }}</strong>
        <p class="text-muted text-sm m-0">
          Step {{ index + 1 }} - {{ state }}
        </p>
      </div>
    </template>
  </MazTimeline>
</template>
```

### Connector slot

```vue
<template>
  <MazTimeline v-model="currentStep" :steps="steps">
    <template #connector="{ index, state }">
      <div class="text-center text-xs text-muted">---</div>
    </template>
  </MazTimeline>
</template>
```

## MazTimeline API

`import MazTimeline from 'maz-ui/components/MazTimeline'`

### Props

- `model-value` (`number`, `v-model`): Index of the active step (v-model).
- `steps` (`MazTimelineItem[]`, required): Array of timeline steps to display.
- `direction` (`MazTimelineDirection`, default: `"auto"`): Layout direction of the timeline - `'horizontal'`: always horizontal - `'vertical'`: always vertical - `'auto'`: horizontal above breakpoint, vertical below. Values: `'horizontal'`, `'vertical'`, `'auto'` (non exhaustive).
- `breakpoint` (`string`, default: `"768px"`): CSS media breakpoint for auto direction (below this value → vertical).
- `color` (`MazTimelineColor`, default: `"primary"`): Color theme for active and completed steps. Values: `'primary'`, `'secondary'`, `'accent'`, `'info'`, `'success'`, `'warning'`, `'destructive'`, `'contrast'` (non exhaustive).
- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the step indicators and typography.
- `show-step-numbers` (`boolean`, default: `true`): Show step numbers inside the indicators.
- `auto-validate-steps` (`boolean`, default: `true`): Automatically show a checkmark icon for completed steps.
- `clickable` (`boolean`, default: `false`): Enable click interaction on steps.
- `animated` (`boolean`, default: `true`): Enable animations (pulse on active, state transitions, connector progress).
- `rounded-size` (`MazTimelineRoundedSize`, default: `'md'`): Border radius of step indicators. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2xl'`, `'3xl'`, `'full'` (non exhaustive).

### Events

- `@update:model-value` (payload: `value: number`): Emitted when the active step changes
- `@click-step` (payload: `payload: { step: MazTimelineItem; index: number; }`): Emitted when a clickable step is clicked

### Slots

- `#indicator`: Custom content for the step indicator circle Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state), `isActive: boolean`, `isCompleted: boolean`.
- `#content`: Full custom content area replacing title and subtitle Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state), `isActive: boolean`, `isCompleted: boolean`.
- `#title`: Custom title content Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state).
- `#subtitle`: Custom subtitle content Bindings: `step: MazTimelineItem` (The step data), `index: number` (The step index), `state: MazTimelineStepState` (The resolved step state).
- `#connector`: Custom connector between steps Bindings: `index: number` (The index of the step before this connector), `isCompleted: boolean`, `isActive: boolean`.