CnWizardDialog
Multi-step modal with per-step slots, back/next navigation, optional
per-step validation, and a single result phase. Each step is declared
in the steps[] prop ({ id, label, optional?, icon? }) and rendered
via a #step-{id} named slot with the navigation API exposed through
the slot scope.
Use CnFormDialog for single-step forms,
CnRichSubmitDialog for single-step
submit-with-files flows, and CnExportWizard
for the specific scope+format+delivery export-trigger shape.
Try it
<template>
<div>
<NcButton @click="show = true">Bulk enrol</NcButton>
<CnWizardDialog
v-if="show"
ref="wizard"
dialog-title="Bulk enrol"
:steps="steps"
:validate="validateStep"
@submit="onSubmit"
@close="show = false">
<template #step-audience="{ stepData, setStepData }">
<CohortPicker :value="stepData.cohort" @input="v => setStepData({ cohort: v })" />
</template>
<template #step-course="{ stepData, setStepData }">
<CoursePicker :value="stepData.course" @input="v => setStepData({ course: v })" />
</template>
<template #step-confirm="{ stepData }">
<p>Enrol {{ stepData.cohort?.size }} learners into {{ stepData.course?.name }}?</p>
</template>
</CnWizardDialog>
</div>
</template>
<script>
import { CnWizardDialog } from '@conduction/nextcloud-vue'
export default {
components: { CnWizardDialog },
data() {
return {
show: false,
steps: [
{ id: 'audience', label: 'Audience' },
{ id: 'course', label: 'Course' },
{ id: 'confirm', label: 'Confirm' },
],
}
},
methods: {
validateStep(stepId, stepData) {
if (stepId === 'audience' && !stepData.cohort) return 'Pick a cohort first.'
if (stepId === 'course' && !stepData.course) return 'Pick a course first.'
return true
},
async onSubmit(payload) {
try {
const { data } = await axios.post('/api/enrolments/bulk', payload)
this.$refs.wizard.setResult({ success: true, message: `Enrolled ${data.count} learners.` })
} catch (e) {
this.$refs.wizard.setResult({ error: e.message })
}
},
},
}
</script>
Slot scope
Each #step-{id} slot receives:
| Field | Type | Description |
|---|---|---|
next | () => Promise<void> | Run validation + advance to the next step. |
back | () => void | Step back. No validation. |
jumpTo | (stepId) => void | Jump to any step. No validation. |
submit | () => Promise<void> | Run validation + emit @submit. |
currentStep | Object | The current step definition. |
stepIndex | number | Zero-based index of the current step. |
totalSteps | number | Total number of declared steps. |
stepData | Object | Shared cross-step data. |
setStepData | (partial: Object) => void | Merge partial into stepData. |
isFirst | boolean | True on the first step. |
isLast | boolean | True on the last step (Next → Submit label flip). |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
steps | Array<{id,label,optional?,icon?}> | — (required) | Step declarations. Order is significant. |
dialogTitle | String | 'Wizard' | Dialog header. |
initialStep | String | '' | Step id to start on; defaults to the first step. |
validate | (stepId, stepData) => Promise<boolean|string> | null | Per-step validator. Return true to advance, a string to show as an error banner + block navigation. |
allowJumpBack | Boolean | true | Allow clicking a completed-step dot to jump back. Forward jumps via the progress indicator are never allowed. |
defaults | Object | {} | Seed values for stepData. |
cancelLabel | String | 'Cancel' | Cancel-button label. |
backLabel | String | 'Back' | Back-button label. |
nextLabel | String | 'Next' | Next-button label. |
submitLabel | String | 'Submit' | Final-step submit-button label. |
closeLabel | String | 'Close' | Close-button label (result phase). |
successText | String | 'Done.' | Default success-banner text when result.message is empty. |
nextDisabled | Boolean | false | Disable Next and Submit, whatever validate would say. next() and submit() from a slot scope do nothing either. CnSetupWizard sets it while a required app is missing. |
cancellable | Boolean | true | Whether the dialog can be dismissed (Cancel button, ESC, backdrop click) before reaching the result phase. false hides Cancel and disables all other close affordances — use for a step that must be completed, not merely skipped. The result-phase Close button is always available. |
skipLabel | String | 'Skip this step' | Skip-button label, on a step marked skippable. |
Events
| Event | Payload | Description |
|---|---|---|
submit | stepData | User reached the final step and confirmed. |
step-change | { stepId, stepIndex, direction } | After every step navigation (next, back, jump). |
close | — | Dialog was dismissed. |
Closing and reopening
The dialog owns its own open state and closes itself for good. Handle @close by unmounting it — v-if="show" with @close="show = false" — and let a fresh mount reopen it. There is no open prop and no public reopen method: a still-mounted instance that has closed stays closed.
This is deliberate. NcDialog does not self-manage open: on any close it clears its internal showModal flag and then sets it back to true about 300 ms later (bookkeeping for the next open). Since it renders on open && showModal, a dialog that leaves open at its true default silently reopens itself after every Cancel / ESC / backdrop click. CnWizardDialog therefore drives open explicitly and pins it false on close, which also means it cannot be revived in place.
Public methods
| Method | Signature | Description |
|---|---|---|
setResult(result) | ({ success?, message?, error? }) | Switch into the terminal result phase + clear loading (Close only). |
setError(message) | (string) | Recoverable failure: clear loading and show message above the still-editable step so the user can fix and resubmit — without entering the result phase. Prefer this over setResult({ error }) when the submit can be retried (e.g. a taken slug). |
The step indicator renders as numbered circles joined by connectors, with a checkmark on completed steps and the active step highlighted in the primary colour.
Slots
#step-{id}— body for each declared step (see scope table above).#result-extra— extra content rendered below the result-phase banner. Scope:{ result }.
Board look
Set look: "board" in the manifest (or pass look="board" to the dialog) and the dialog draws the board dialog of the screens. An app that sets nothing renders exactly as before.
| Prop | Default | What it does |
|---|---|---|
look | follows the app | board or nextcloud. The prop wins over the app. |
width | per component | confirm (560), form (640) or wizard (720). No other width is reachable. |
eyebrow | empty | A context line above the title, 13px in sentence case. Not part of the accessible name. |
subtitle | empty | A sentence under the title. |
Widths are capped at the viewport minus 32px. Theme hooks: --cn-dialog-danger (fill of a destructive primary, default --color-error), --cn-dialog-eyebrow-color, --cn-dialog-eyebrow-transform (uppercase for capitals) and --cn-dialog-eyebrow-tracking.
Stepper, eyebrow and footer
The stepper is an ordered list in both looks, with aria-current="step" on the current step; it is no longer a tablist. A finished step is a button only when allowJumpBack is true (e2e tests that selected role="tab" inside a wizard need the new selector).
In the board look the stepper draws 28px circles with the label beside each: a green check on a finished step, a filled primary circle on the current one and an outlined circle on the rest, joined by a 2px connector. The eyebrow reads like New newsletter, step 2 of 5 and follows the step: eyebrowContext sets the context (default the dialog title) and stepEyebrow translates the sentence with {context}, {step} and {total}.
With stepHeading the board dialog is headed by the current step's label, and the dialog title stays in the eyebrow as its context (Set up Dossiq, step 4 of 5 over Example data, board DqInstellen). The result phase and the Nextcloud look keep dialogTitle as the heading. CnSetupWizard turns it on.
The footer reads Cancel, Back (chevron left) and the primary: Next with a chevron right, or on the last step submitLabel with submitIcon (default a check). CnSetupWizard passes these through.
See also
CnFormDialog— single-step schema-driven form.CnRichSubmitDialog— single-step rich submit (reason + files + notes).CnExportWizard— pre-built export-trigger wizard.