Stepper

Overview

The Stepper component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Steppers guide users through multi-step processes, reducing cognitive load by showing only one step at a time while maintaining context of the overall flow.

Mental model

When to use

When not to use

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

import { Stepper, StepperProgress } from '@byteion/react';

const steps = [
  { id: '1', label: 'Account',   description: 'Email + password' },
  { id: '2', label: 'Profile',   description: 'Name + photo' },
  { id: '3', label: 'Workspace', description: 'Invite teammates' },
];

export default function StepperDemo() {
  return (
    <div className="space-y-10 p-6">
      <Stepper steps={steps} current={1} />
      <StepperProgress steps={steps} current={1} />
    </div>
  );
}

<script setup lang="ts">
import { Stepper } from '@byteion/vue';

const steps = [
  { id: '1', label: 'Account',   description: 'Email + password' },
  { id: '2', label: 'Profile',   description: 'Name + photo' },
  { id: '3', label: 'Workspace', description: 'Invite teammates' },
];
</script>

<template>
  <div class="space-y-10 p-6">
    <Stepper :steps="steps" :current="1" />
  </div>
</template>

States

This component reacts seamlessly to the following interaction and data states:

• complete — complete state.
• current — current state.
• pending — pending state.
• error — Validation failed — red border and error message.
• default — Resting appearance before interaction.
• hover — Pointer is over the element — visual feedback via color or shadow.
• focus — Keyboard or tab focus — shows ring indicator for accessibility.
• active — Currently selected or in use.
• disabled — Non-interactive — grayed out, cursor not-allowed.

Anatomy

Usage guidelines

• Limit to 7 steps maximum.
• Allow going back to previous steps.
• Save progress between steps.

Do and Don't

Accessibility

Each step is a link or button. Current step has aria-current="step". Completed steps are navigable.

Customization

Active step color follows --primary. Completed uses --success.

import { cva, cn, type VariantProps } from '@byteion/react';

const myStepper = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myStepper>;

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myStepper = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myStepper({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX

API Reference

Static HTML. Step navigation controlled by parent flow logic.

export interface StepperProps extends Omit<HTMLAttributes<HTMLOListElement>, 'children'> {
  steps: StepperStep[];
  /** 0-based index of the active step. Used only when `steps[i].state` is unset. */
  currentStep?: number;
  /** Layout. */
  orientation?: 'horizontal' | 'vertical' | 'compact';
}

export interface StepperProps {
  steps: StepperStep[];
  /** 0-based index of the active step. Used only when `steps[i].state` is unset. */
  currentStep?: number;
  /** Layout. */
  orientation?: 'horizontal' | 'vertical' | 'compact';
}

Developer tips

Common mistakes

Production usage tips

Premium examples

Advanced patterns available in Byteion Pro:

Related components

• Button — advance or submit step actions
• Alert — show per-step validation or error messages
• Form Field — wrap stepper content in validated forms
• Input — collect step-level data
• Card — contain each step's content
• Progress — standalone progress indicator
• Tabs — non-sequential section switching
• Modal — lightweight stepped flows in dialogs
• Pagination — page-based navigation (not for multi-step flows)