Skip to main content

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.

import { Wizard, WizardStep } from '@patine-ui/pro';
Loading…
<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="[email protected], [email protected]" />
  </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>

Try the props​

Props
indicator
layout
transition
design
<Wizard
steps={steps}
onComplete={finish}
onCancel={close}
/>

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.

Loading…
<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.

Loading…
<Wizard steps={steps} layout="sidebar" linear={false} transition="fade" onComplete={() => {}} style={{ width: '100%' }} />

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.

Loading…
<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​

PropTypeDefaultDescription
stepsWizardStepConfig[]—{ value, title, description?, icon?, content?, validate?, optional? }. Or <WizardStep> children.
value / defaultValue / onValueChangestringfirst stepThe current step.
onComplete() => void | Promise—Runs on Finish after the last step validates.
onCancel() => void—Shows Cancel on the first step.
linearbooleantrueSteps 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—
labelsPartial<WizardLabels>back, next, finish, skip, cancel, step, invalid, optional
density / animate / design / theme / accessibilityLabel / style