C&C Docs
Log in

cnc-wizard

A multi-step form: a sidebar of steps, a rendered form per step, and navigation gated on validation. Each step's form is a cnc-form-renderer layout, so a wizard is a list of those plus rules about moving between them.

Quick start

Bind a steps array and a data object of its own. Each step names a form layout; the widget renders it, validates it, and moves when it passes. The working examples are below — their steps come from this page's block controller. 

<cnc-wizard
  $steps="steps"
  $data="answers"
  @change="track($event.detail.index)"
  @submit="save($event.detail.data)"
></cnc-wizard>

// a step
{
  name: 'account',
  title: 'Account',
  description: 'How we reach you',
  form: { /* a cnc-form-renderer layout */ }
}

Step keys

The three hooks may be FUNCTIONS only when the steps come from a widget controller. Block state is serialised to the client as JSON, which drops functions — so a step defined in block state must use the plain-value form of lock and back, and cannot supply validate at all.

Key Purpose
name The step's key in data. Its answers live under it.
title / description Shown in the sidebar and above the form.
form A cnc-form-renderer layout — the same JSON a cnc-form-builder export produces.
validate Overrides the built-in check with your own; called with (data, errors) and must return truthy for the user to move forward. Without it the widget walks the step's form layout and checks required fields.
lock Pins navigation on this step — no Back, no sidebar jump. A function called with (data, errors), or a plain truthy value.
back Whether leaving this step BACKWARDS is allowed. A function or a plain value; absent means yes.

How navigation is gated

  • Forward requires validate (or the built-in required-field walk) to pass. The button is disabled as well as guarded, so a blocked step cannot be advanced by any route.
  • Back is refused on the first step, while the step is locked, and when the step's own back hook says no.
  • The sidebar jumps BACKWARDS ONLY, to an already-completed step, and only while unlocked. Forward movement always goes through the button, so it can never skip validation.

Usage guidance

Keep data per wizard. Fields write into it directly, so two wizards bound to one object collect into the same place and overwrite each other — give each its own key.

Remember what JSON drops. Steps defined in block state are serialised to the client, so validate functions vanish and only the plain-value forms of lock and back survive. Where real validation logic is needed, the steps have to come from a widget controller.

Use the absence of change as your signal. A refused move is silent by design — nothing moves and nothing is emitted — so surface the reason yourself through errors, or the user presses Continue and sees nothing happen.

For a linear flow with no per-step validation, cnc-slides plus cnc-steps is lighter. This widget earns its weight when the gating is the point.

← Back to Widgets