VfNav

Basic

VfNav renders the Back, Next, and Finish buttons in a stepped form. Override the nav slot on VfForm to render VfNav with custom props or alongside additional content.

<VfForm stepped hide-errors>
  <template #nav="{ pager }">
    <VfNav
      :pager="pager"
      next="Continue"
      finish="Done"
    />
  </template>
  <VfGroup name="personal" page="Personal">
    <VfText name="name" label="Name" />
  </VfGroup>
  <VfGroup name="contact" page="Contact">
    <VfText name="email" label="Email" />
  </VfGroup>
  <VfGroup name="address" page="Address">
    <VfText name="city" label="City" />
  </VfGroup>
</VfForm>

<template>
  <VfForm stepped hide-errors>
    <template #nav="{ pager }">
      <VfNav
        :pager="pager"
        next="Continue"
        finish="Done"
      />
    </template>
    <VfGroup name="personal" page="Personal">
      <VfText name="name" label="Name" />
    </VfGroup>
    <VfGroup name="contact" page="Contact">
      <VfText name="email" label="Email" />
    </VfGroup>
    <VfGroup name="address" page="Address">
      <VfText name="city" label="City" />
    </VfGroup>
  </VfForm>
</template>

<script setup lang="ts">
import { defineSchema, defineSlot, useForm } from '@vueform/ui'
import { h, resolveComponent } from 'vue'

const schema = defineSchema({
  personal: {
    type: 'group',
    page: 'Personal',
    schema: {
      name: { type: 'text', label: 'Name' },
    },
  },
  contact: {
    type: 'group',
    page: 'Contact',
    schema: {
      email: { type: 'text', label: 'Email' },
    },
  },
  address: {
    type: 'group',
    page: 'Address',
    schema: {
      city: { type: 'text', label: 'City' },
    },
  },
})

const [MyForm] = useForm({
  schema,
  stepped: true,
  hideErrors: true,
  slots: {
    nav: defineSlot('VfForm.nav', {
      props: ['pager'],
      setup: (props) => () => {
        const VfNav = resolveComponent('VfNav')

        return h(VfNav, {
          pager: props.pager,
          next: 'Continue',
          finish: 'Done',
        })
      },
    }),
  },
})
</script>

<template>
  <MyForm />
</template>

Props

Configure the component's behavior and appearance with these props.

Component

Prop	Default	Description
pager	—	Required. The pager instance managing step/tab navigation state.
back	—	The label text for the "back" navigation button.
next	—	The label text for the "next" navigation button.
finish	—	The label text for the "finish" navigation button.
hideBack	true	Whether to hide the "back" navigation button.
position	'auto'	The alignment of the navigation buttons: 'left', 'center', 'right', 'fluid' (stretched to full width), or 'auto'.

Customization

Prop	Default	Description
parts	—	Custom DOM attribute overrides for the component's structural parts.
class	—	CSS classes to apply to the component's root element.
classes	—	Custom CSS class overrides for the component's structural parts.
reclass	—	CSS class overrides that replace (rather than merge with) default classes.
slots	—	Custom Vue components to use for named slots. Every component resolves it through the standard outlets pipeline (see useOutlets).
presets	—	Named configuration presets to apply to the component.
template	—	A custom Vue component to use as the template instead of the default.
component	—	A custom Vue component to render in the component's default slot.

Context

Reactive properties and methods accessible on the component's Context object.

General

Name	Description
props	The resolved component props with defaults applied.

Navigation

Name	Description
backLabel	The resolved label text for the "back" button.
nextLabel	The resolved label text for the "next" button.
finishLabel	The resolved label text for the "finish" button.
describedby	The aria-describedby value linking to the status element when on the last enabled page with errors or loading.
statusId	The HTML id for the navigation status message element.
fluid	Whether the navigation buttons are stretched to the full available width (position: 'fluid').

State

Name	Description
loading	Whether the current page is in a loading state.

Layout

Name	Description
classes	The resolved CSS class map for the component.
parts	The resolved DOM attribute overrides for internal elements.

Events

Name	Description
fire()	Fires an event synchronously, invoking before, main, and after listeners in order.
fireAsync()	Fires an event asynchronously, awaiting each callback and short-circuiting when any returns false.
on()	Subscribes a callback to a specific event.
off()	Removes a previously registered event callback.
onBefore()	Registers a callback that runs before the main event listeners.
onAfter()	Registers a callback that runs after the main event listeners.

Events

Events emitted by the component. See Events for details.

Name	Params	Description
beforeMount	context$	Emitted before the component is mounted.
mounted	context$	Emitted after the component is mounted.
beforeUnmount	context$	Emitted before the component is unmounted.
unmounted	context$	Emitted after the component is unmounted.
updated	context$	Emitted after the component is updated.

Slots

Named Slots for replacing parts of the component's rendering.

Name	Scope	Description
template	context	Slot that replaces the entire component rendering. Receives the full component context as a single context prop.
back	label pager form$ disabled fluid bindings back	Slot that replaces the back button. The payload is what VfNav provides — a fixed list, independent of the registered VfButton's prop surface, since the slot may render anything.
back-text	label pager form$	Slot that replaces the back button's text label.
next	label pager form$ disabled loading fluid bindings next	Slot that replaces the next button. The payload is what VfNav provides — a fixed list, independent of the registered VfButton's prop surface, since the slot may render anything.
next-text	label pager form$	Slot that replaces the next button's text label.
finish	label pager form$ disabled loading fluid bindings finish	Slot that replaces the finish button. The payload is what VfNav provides — a fixed list, independent of the registered VfButton's prop surface, since the slot may render anything.
finish-text	label pager form$	Slot that replaces the finish button's text label.

Parts

DOM attribute overrides targeting internal elements. See Parts for details.

root

The root navigation element.

Element	<div>
Classes	.vf-nav
Bindings	data-position data-no-back

back

The back button element.

Element	<VfButton>
Classes	.vf-nav-back
Bindings	aria-disabled

next

The next button element.

Element	<VfButton>
Classes	.vf-nav-next
Bindings	data-loading aria-busy aria-disabled aria-describedby

finish

The finish button element.

Element	<VfButton>
Classes	.vf-nav-finish
Bindings	data-loading aria-busy aria-disabled aria-describedby

srOnlyLoading

The screen-reader-only loading indicator element.

Element	<span>
Bindings	id role

Tokens

All the CSS variables that control this component's appearance with default values in the default theme. See Themes & Tokens for details.

:root {
  /**
   * Component tokens
   * -------------------------------------------------------------------------- */
  --vf-nav-gutter: var(--vf-gutter);
  --vf-nav-justify: space-between;
  --vf-nav-margin: var(--vf-gutter) 0 0 0;
}

{
  /**
   * Component tokens
   * -------------------------------------------------------------------------- */
  navGutter: '$gutter',
  navJustify: 'space-between',
  navMargin: '$gutter 0 0 0',
}