Container

Import

import { Wizard } from '@dnb/eufemia/extensions/forms'
render(<Wizard.Container />)

Description

The Wizard.Container is a container component for multi-page forms including a StepIndicator.

Use the Wizard.Step component to define the wizard steps.

import { Form, Wizard } from '@dnb/eufemia/extensions/forms'

const MyForm = () => {
  return (
    <Form.Handler>
      <Wizard.Container>
        <Wizard.Step title="Step 1">...</Wizard.Step>
      </Wizard.Container>
    </Form.Handler>
  )
}

You can also split or separate the Wizard.Step and its content:

import { Form, Wizard } from '@dnb/eufemia/extensions/forms'

// You can use the `Wizard.Step` in an external component like this:
const Step1 = () => (
  <Wizard.Step title="Step 1">
    <Form.MainHeading>Heading</Form.MainHeading>
    <Form.Card>
      <P>Contents</P>
    </Form.Card>
    <Form.Card>
      <P>Contents</P>
    </Form.Card>

    <Wizard.Buttons />
  </Wizard.Step>
)

const MyForm = () => {
  return (
    <Form.Handler>
      <Wizard.Container>
        <Step1 />
      </Wizard.Container>
    </Form.Handler>
  )
}

You can mix and match the usage of Wizard.Step and Flex.Stack depending on your needs:

import { Form, Wizard } from '@dnb/eufemia/extensions/forms'

const Step2 = () => (
  <Flex.Stack>
    <Form.Card>
      <P>Contents</P>
    </Form.Card>
    <Form.Card>
      <P>Contents</P>
    </Form.Card>

    <Wizard.Buttons />
  </Flex.Stack>
)

const MyForm = () => {
  return (
    <Form.Handler>
      <Wizard.Container>
        <Wizard.Step title="Step 2">
          <Form.MainHeading>Heading</Form.MainHeading>
          <Step2 />
          <Wizard.Buttons />
        </Wizard.Step>
      </Wizard.Container>
    </Form.Handler>
  )
}

Controlling the wizard steps

To define a different initial index (than 0), you can use initialActiveIndex property.

Note: When using initialActiveIndex, there may be previous steps with unknown field validation statuses. To address this, you can use the keepInDOM property to ensure that some or all steps are not removed from the DOM, so validation runs on fields in previous steps.

For controlling the wizard steps interactively, you can use the Wizard.useStep hook:

import { Form, Wizard } from '@dnb/eufemia/extensions/forms'

const MyStep = () => {
  const { setActiveIndex, activeIndex } = Wizard.useStep()
  return (
    <Form.Card>
      <Button onClick={() => setActiveIndex(1)}>Go to step 2</Button>
    </Form.Card>
  )
}

const MyForm = () => {
  return (
    <Form.Handler>
      <Wizard.Container initialActiveIndex={3}>
        <Wizard.Step>
          <MyStep />
        </Wizard.Step>
      </Wizard.Container>
    </Form.Handler>
  )
}

When using the useStep hook outside of the Wizard.Container context, you need to provide an unique id (string, function, object or React Context as the reference):

import { Form, Wizard } from '@dnb/eufemia/extensions/forms'

const myContainerId = 'unique-id' // or a function, object or React Context reference

const MyForm = () => {
  const { setActiveIndex, activeIndex } = Wizard.useStep(myContainerId)

  return (
    <Form.Handler>
      <Wizard.Container id={myContainerId}>
        <Wizard.Step>
          <Button onClick={() => setActiveIndex(0)}>Step 1</Button>
        </Wizard.Step>
        <Wizard.Step>
          <Button onClick={() => setActiveIndex(1)}>Step 2</Button>
        </Wizard.Step>
      </Wizard.Container>
    </Form.Handler>
  )
}

You can also prevent the user from navigating to the next or previous step, by using the preventNavigation callback function found as the third parameter, in the onStepChange event.

import { Form, Wizard } from '@dnb/eufemia/extensions/forms'

const MyForm = () => {
  return (
    <Form.Handler>
      <Wizard.Container
        onStepChange={(step, type, { preventNavigation }) => {
          if (step === 2 && type === 'next') {
            preventNavigation()
          }
        }}
      >
        <Wizard.Step title="Step 1">
          <P>Step 1</P>
          <Wizard.Buttons />
        </Wizard.Step>
        <Wizard.Step title="Step 2">
          <P>Step 2</P>
          <Wizard.Buttons />
        </Wizard.Step>
        <Wizard.Step title="Step 3">
          <P>Step 3</P>
          <Wizard.Buttons />
        </Wizard.Step>
      </Wizard.Container>
    </Form.Handler>
  )
}

Modes

The strict mode is the default. The user can only navigate forward using the Wizard.NextButton, not via the menu. However, the previous step remains active, allowing the user to go back at any time – even if there are errors in the current step.
Use loose mode if the user should be able to navigate freely between all steps, including those that have not been visited before. When there is an error in the current step, the user can navigate to other steps via the menu, but not via the Wizard.NextButton.

Accessibility

The Wizard.Step component uses an aria-label attribute that matches the title property value. The step content is enclosed within a section element, which further enhances accessibility.

Whenever a new step becomes active, it automatically receives focus, ensuring that screen readers convey the relevant information to users.

Additionally, during a step change the Wizard will scroll to the top of the form, to ensure the user is aware of the new content.

#Container

#Import

#Description

#Controlling the wizard steps

#Modes

#Accessibility