# React Native Wizard, multi-step form (Pro)

> A React Native wizard for iOS, Android and the web: a multi-step form with numbered steps, a progress bar, dots or a side list, sync and async validation with messages, optional steps with Skip, slide transitions, and an async finish. Accessible and themeable.

# Wizard Pro

A task in steps: setup, onboarding, a long form. The wizard shows where the user is (numbered steps, a progress bar, dots or a list beside the form), validates each step on Next, sync or async, and says what's wrong, skips optional steps, slides each step in, and spins Finish while `onComplete` runs. Give the steps as a `steps` array, or as `<WizardStep>` children.

```tsx
import { Wizard, WizardStep } from '@patine-ui/pro';
```

```tsx live full
import { Wizard, WizardStep } from '@patine-ui/pro';

export default function Example() {
  const [name, setName] = React.useState('');
  const [done, setDone] = React.useState(false);
  if (done) return <Text>All set, {name}!</Text>;
  return (
    <Wizard onComplete={() => new Promise((resolve) => setTimeout(() => { setDone(true); resolve(); }, 1200))} style={{ width: 560 }}>
      <WizardStep value="you" title="About you" description="We'll use this on your profile" validate={() => name.trim().length > 1 || 'Enter your name'}>
        <TextField label="Name" value={name} onValueChange={setName} placeholder="Ada Lovelace" />
      </WizardStep>
      <WizardStep value="team" title="Invite your team" optional>
        <TextField label="Emails" placeholder="maya@acme.com, omer@acme.com" />
      </WizardStep>
      <WizardStep value="plan" title="Pick a plan" description="You can change it anytime">
        <RadioGroup options={[{ label: 'Free', value: 'free' }, { label: 'Pro', value: 'pro' }]} defaultValue="free" />
      </WizardStep>
    </Wizard>
  );
}
```

## Example: list a flat for rent

A rental site's listing flow: the address must be filled before moving on, photos are optional, and the price step checks the rent is sensible. Finishing shows the listing's summary.

```tsx live wide
import { useState } from 'react';
import { Box, NumberField, Text, TextField } from 'patine-ui';
import { Wizard, WizardStep } from '@patine-ui/pro';

export default function Example() {
  const [street, setStreet] = useState('');
  const [rooms, setRooms] = useState<number | null>(2);
  const [rent, setRent] = useState<number | null>(1650);
  const [done, setDone] = useState(false);
  if (done)
    return (
      <Box border radius="lg" padding="lg" gap="xs" style={{ width: '100%', maxWidth: 480 }}>
        <Text weight="semibold">Listed: {street}</Text>
        <Text color="textSecondary">{rooms} rooms · €{rent} a month · goes live after a quick check</Text>
      </Box>
    );
  return (
    <Wizard onComplete={() => new Promise<void>((resolve) => setTimeout(() => { setDone(true); resolve(); }, 900))} style={{ width: '100%', maxWidth: 560 }}>
      <WizardStep value="where" title="Where is it?" validate={() => street.trim().length > 4 || 'Enter the street and number'}>
        <TextField label="Street and number" placeholder="Prinsengracht 263" value={street} onValueChange={setStreet} />
        <NumberField label="Rooms" value={rooms} onValueChange={setRooms} min={1} max={10} />
      </WizardStep>
      <WizardStep value="photos" title="Photos" description="Listings with photos get 4× the viewings" optional>
        <Text color="textSecondary">Add photos from your phone, or skip and add them later.</Text>
      </WizardStep>
      <WizardStep value="price" title="Rent" validate={() => (rent ?? 0) >= 300 || 'Rent must be at least €300'}>
        <NumberField label="Monthly rent" value={rent} onValueChange={setRent} min={0} step={50} formatValue={(v) => `€${v}`} helperText="Similar flats nearby: €1,500 – €1,900" />
      </WizardStep>
    </Wizard>
  );
}
```

## Validation

`validate` runs on Next. Return `true` (or nothing) to go on, `false` to stay with the default message, or a message to show. It may be async: Next spins while it runs, as when an email is checked on the server. A failed step is marked in the indicator.

## Indicators and layout

`indicator` is `'steps'` (numbered, with a check on each done step), `'progress'` (a bar with "Step 2 of 4", the default under 480 points wide), `'dots'` or `'none'`. `layout="sidebar"` lists the steps in a column beside the form, as desktop setup flows do; with `linear={false}` the user can jump to any step from it.

```tsx live full
import { Wizard } from '@patine-ui/pro';

const steps = [
  { value: 'workspace', title: 'Workspace', description: 'Name and URL', content: <TextField label="Workspace name" placeholder="Acme" /> },
  { value: 'branding', title: 'Branding', description: 'Logo and colors', optional: true, content: <Text>Upload a logo and pick a color.</Text> },
  { value: 'billing', title: 'Billing', description: 'Card on file', content: <TextField label="Card number" placeholder="4242 4242 4242 4242" /> },
  { value: 'review', title: 'Review', content: <Text>Everything looks good.</Text> },
];

export default function Example() {
  return <Wizard steps={steps} layout="sidebar" linear={false} transition="fade" onComplete={() => {}} style={{ width: '100%' }} />;
}
```

## Controlled, with your own footer

`value` and `onValueChange` control the step. `renderFooter` gets the wizard's state and moves (`next`, `back`, `skip`, `goTo`, `index`, `count`, `isLast`, `busy`, `error`) to draw your own buttons. A step's `content` can be a function of the same.

```tsx live full
import { Wizard } from '@patine-ui/pro';

const steps = ['Shipping', 'Payment', 'Confirm'].map((title) => ({
  value: title.toLowerCase(),
  title,
  content: ({ index, count }) => <Text>{`${title} form (${index + 1} of ${count})`}</Text>,
}));

export default function Example() {
  const [step, setStep] = React.useState('shipping');
  return (
    <Wizard
      steps={steps}
      value={step}
      onValueChange={setStep}
      indicator="dots"
      renderFooter={({ next, back, isFirst, isLast }) => (
        <View style={{ flexDirection: 'row', gap: 8 }}>
          {!isFirst ? <Button variant="ghost" onPress={back}>Back</Button> : null}
          <Button style={{ flex: 1 }} onPress={next}>{isLast ? 'Place order' : 'Continue'}</Button>
        </View>
      )}
      style={{ width: 420 }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `WizardStepConfig[]` | — | `{ value, title, description?, icon?, content?, validate?, optional? }`. Or `<WizardStep>` children. |
| `value` / `defaultValue` / `onValueChange` | `string` | first step | The current step. |
| `onComplete` | `() => void \| Promise` | — | Runs on Finish after the last step validates. |
| `onCancel` | `() => void` | — | Shows Cancel on the first step. |
| `linear` | `boolean` | `true` | Steps in order; the indicator goes back to visited steps only. |
| `indicator` | `'steps'` \| `'progress'` \| `'dots'` \| `'none'` | `'steps'` (`'progress'` when narrow) | |
| `layout` | `'top'` \| `'sidebar'` | `'top'` | |
| `transition` | `'slide'` \| `'fade'` \| `'none'` | `'slide'` | |
| `renderFooter` | `(wizard) => ReactNode` | — | |
| `labels` | `Partial<WizardLabels>` | | back, next, finish, skip, cancel, step, invalid, optional |
| `density` / `animate` / `design` / `theme` / `accessibilityLabel` / `style` | | | |
