API Reference
Props
Full prop reference for the FormWizard component and FormWizard.TabContent.
Props
FormWizard Component
Content
| Prop | Description | Sample |
|---|---|---|
title | Wizard title (string or React node). A node replaces the whole header. | v1 basic |
subtitle | Optional wizard subtitle text. | v1 basic |
children | Children API content using FormWizard.TabContent. | v1 basic |
schema | Schema API definition (FormWizardSchema). If both schema and children are passed, schema wins. | v1 schema api |
data | Controlled wizard data object. | v1 conditional steps |
onDataChange | Callback fired when wizard data changes. | v1 schema api |
Appearance
| Prop | Description | Sample |
|---|---|---|
variant v2 | Visual skin: "modern" (default) or "legacy" for the v1 appearance. | theming |
colorScheme v2 | "auto" (default), "light" or "dark". Pins the scheme instead of following the OS or your .dark class. | dark mode |
color | Main accent colour. Prefer theme.primaryColor — color is an inline style and cannot be overridden by CSS. | v1 custom colors |
theme v1.2 | Theme tokens written as --rfw-* CSS custom properties on the root. Overrides one value without restating a palette. | theming |
unstyled v1.2 | Drops every bundled class and inline colour so only your own styles apply. Default: false. | unstyled |
classNames v1.2 | Per-element class overrides (WizardClassNames). Merged with the defaults, or replacing them when unstyled. | unstyled |
shape | Tab shape (circle, square or tab). | v1 square shape |
stepSize | Step size: xs, sm, md, lg. Default: md. | v1 step sizes |
layout | Layout direction: horizontal or vertical. Default: horizontal. | v1 vertical layout |
showProgressBar | Toggle the progress bar between completed steps. Default: true. | v1 progress bar |
inlineStep | Compact inline step layout. Default: false. | v1 inline steps |
darkMode | Enables dark mode visuals. Default: false. | v1 dark mode |
customDarkModeColor | Custom dark-mode colour tokens object. Prefer theme, which works in both light and dark. | v1 dark mode |
removeBackgroundTab | Removes the default tab background fill. | legacy remove tab bg |
removeBackgroundTabTransparentColor | Background colour to apply under transparent tab icons. | legacy remove tab bg |
style v1.2 | Extra inline styles for the root element. | — |
Buttons
| Prop | Description | Sample |
|---|---|---|
nextButtonText | Text label for the next button. Default: Next. | v1 progress bar |
backButtonText | Text label for the back button. Default: Back. | v1 progress bar |
finishButtonText | Text label for the finish button. Default: Finish. | v1 progress bar |
nextButtonTemplate | Custom renderer for the next button. Receives the advance callback. | v1 custom button templates |
backButtonTemplate | Custom renderer for the back button. Receives the go-back callback. | v1 custom button templates |
finishButtonTemplate | Custom renderer for the finish button. Receives the submit callback. | v1 custom button templates |
Navigation and state
| Prop | Description | Sample |
|---|---|---|
startIndex | Initial active step index. Clamped into range on the first render. | legacy step index |
disableBackOnClickStep | Prevents navigating by clicking step markers. | v1 complete showcase |
persist v1.2 | { key, storage } — keeps wizard data across reloads. storage is "session" (default) or "local". | persistence |
syncToUrl v1.2 | true or { param } — mirrors the active step into a query parameter (1-based). Default param: step. | persistence |
keyboardNavigation v1.2 | Enable ← → Home End navigation. Default: true. | accessibility |
swipeNavigation v1.2 | Enable horizontal swipe on touch devices. Default: true. | accessibility |
Accessibility
| Prop | Description | Sample |
|---|---|---|
announceStepChanges v1.2 | Announce step changes through an aria-live region and move focus to the revealed panel. Default: true. | accessibility |
ariaLabel v1.2 | Accessible name for the wizard region. Default: "Form Wizard". Give each wizard its own when a page has several. | accessibility |
Events
| Prop | Description | Sample |
|---|---|---|
onComplete | Called on finish, with the wizard data: (data?: WizardData) => void. | v1 schema api |
onTabChange | Called when the active step changes with { prevIndex, nextIndex, stepId? }. Does not fire on mount as of v1.2. | events |
FormWizard.TabContent Component
Used to define each step in the children API:
| Prop | Description | Sample |
|---|---|---|
id | Stable step id, used by goToTabById and reported as stepId. | v1 complete showcase |
title | Tab title text. | v1 basic |
icon | Tab icon (class-name string or React node). | v1 custom react icons |
condition | Condition function deciding whether the step is visible. | v1 conditional steps |
validate | Validation function returning true, false, or an error message string. | validation |
isValid | Static boolean validity flag. Prefer validate for anything data-dependent. | v1 validation |
validationError | Called when an invalid step blocks navigation. | v1 validation |
showErrorOnTab | Shows the error style on the tab when invalid. | v1 validation |
showErrorOnTabColor | Error colour for the tab icon, title and progress border. | v1 validation |
Step options (schema API)
Each entry in schema.steps accepts:
| Option | Type | Description |
|---|---|---|
id | string | Stable step id. |
title | string | Step label. |
icon | string | ReactNode | Icon class name or node. |
content | ReactNode | (ctx) => ReactNode | Step body, or a function of the current data. |
condition | (ctx) => boolean | Hide the step when it returns false. |
validate | (ctx) => true | string | false | Block navigation; a string is the message shown. |
showErrorOnTab | boolean | Mark the step marker on failure. |
showErrorOnTabColor | string | Colour used to mark it. |
validate runs on every render, so it must be synchronous and free of side
effects — never await, never set state from it. For asynchronous checks, do
the work in your own handler, write the result into wizard data, and have the
validator read that. See the
async verification pattern.
Theme tokens
theme accepts any subset of these; anything omitted falls back to the
stylesheet default.
| Token | CSS custom property |
|---|---|
primaryColor | --rfw-primary |
backgroundColor | --rfw-bg |
backgroundColor | --rfw-bg |
textColor | --rfw-text |
titleColor | --rfw-title |
subtitleColor | --rfw-subtitle |
tabColor | --rfw-tab |
tabIconColor | --rfw-tab-icon |
borderColor | --rfw-border |
buttonColor | --rfw-button |
buttonTextColor | --rfw-button-text |
finishButtonColor | --rfw-finish-button |
finishButtonTextColor | --rfw-finish-button-text |
errorColor | --rfw-error |
borderRadius | --rfw-radius |
classNames keys
root, header, title, subtitle, navigation, stepList, step,
stepActive, stepIcon, stepTitle, content, footer, backButton,
nextButton, finishButton.
Exported types
import type {
FormWizardProps,
FormWizardMethods,
FormWizardSchema,
WizardStepSchema,
WizardData,
WizardTheme,
WizardClassNames,
WizardPersistOptions,
WizardUrlSyncOptions,
WizardStepChangeEvent,
WizardCondition,
WizardValidation,
WizardValidationResult,
WizardConditionContext,
WizardValidationContext,
UseWizardOptions,
UseWizardReturn,
TabContentProps,
} from "react-form-wizard-component";Releases 1.0.0–1.1.1 pointed types at a file that was never generated, so
TypeScript reported TS7016: Could not find a declaration file. That is fixed,
and type resolution is now verified in CI under bundler, node16 and
node10.
For callback details see Events; for imperative methods see References.