FormStep

Renders a form step in FormSteps component.

Basic Usage

<FormStep> component can be used in <FormSteps> component:

vue

<template>
  <Vueform>
    <template #empty>
      <FormSteps>
        <FormStep
          name="account"
          :elements="['email', 'password']"
        >Account</FormStep>
        <FormStep
          name="personal"
          :elements="['name', 'bio']"
        >Personal</FormStep>
        <FormStep
          name="social"
          :elements="['facebook', 'twitter']"
        >Social</FormStep>
      </FormSteps>

      <FormElements>
        <TextElement
          name="email"
          label="Email"
        />
        <TextElement
          input-type="password"
          name="password"
          label="Password"
        />
        <TextElement
          name="name"
          label="Name"
        />
        <TextareaElement
          name="bio"
          label="bio"
        />
        <TextElement
          name="facebook"
          label="Facebook"
        />
        <TextElement
          name="twitter"
          label="Twitter"
        />
      </FormElements>

      <FormStepsControls />
    </template>
  </Vueform>
</template>

Configuration options can be passed over as regular component props. Check out Options section for available configuration options.

Options

Find below the list of options that can use to configure FormStep component. Options can be passed to the component via props.

labels

Type: object
Default: {}

vue

<FormStep :labels="{
  next: 'Next »',
  previous: '« Previous',
  finish: 'Complete'
}" ... />

Overrides the Previous / Next / Finish button labels for the step which gets rendered by FormStepsControls component.

buttons

Type: object
Default: {}

vue

<FormStep :buttons="{
  next: true,
  previous: false,
  finish: true
}" ... />

Decides whether Previous / Next / Finish buttons should be rendered for the step in FormStepsControls component.

elements

Type: array
Default: []

vue

<FormStep :elements="['name', 'email', 'password']" ... />

The names of highest level form elements the step should contain.

name

Type: string|number
Required: true

vue

<FormStep name="personal_information" ... />

The name of the step.

label

Type: string|object|function

template

<!-- Using string/HTML --->
<FormStep label="Profile" ... />

<!-- Using component --->
<FormStep :label="{ template: '<span>Profile</span>' }" ... />

<!-- Using function --->
<FormStep name="profile" :label="step$ => _.upperFirst(step$.name)" />

The step's label. Can be defined as a string, a Vue component object with a render function or as a function that receives step$ as its first a param.

Can also be defined via #default slot.

conditions

Type: array
Default: []

template

<FormSteps>
  <FormStep label="First" ... />
  <FormStep label="Second" :conditions="[['checkbox', true]]" ... />
  <FormStep label="Third" ... />
</FormSteps>

<!-- ... --->

<CheckboxElement name="checkbox" text="Check me" ... />

Shows or hides the step based on the provided conditions. If any of the the conditions is unfulfilled the step will be hidden.

Conditions can be provided as an array, where each item has to be either an array or a function.

If a condition is provided as an array, the first value must be the path of an element which value should be watched. The second is an operator that should define the type of comparison. The third is the expected value of the element.

vue

<FormStep :conditions="[['element', '==', 'expected_value']]" ... />

Hint: In case you want to check for equality you might leave the operator and pass the expected value as the second param:

vue

<FormStep :conditions="[['element', 'expected_value']]" ... />

Available operators:

== - expect equality
!= - expect inequality
> - expect the other element's value(s) to be higher
>=- expect the other element's value(s) to be higher or equal
< - expect the other element's value(s) to be lower
<= - expect the other element's value(s) to be lower or equal
^ - expect the other element's value to start with
$ - expect the other element's value to end with
* - expect the other element's value to contain
in - expect to be among an array of values
not_in - expect not to be among an array of values
today - expect to be today
before - expect to be before a date (value can be a YYYY-MM-DD date string or today)
after - expect to be after a date (value can be a YYYY-MM-DD date string or today)

The expected value can also be defined as an array in which case any of its values will fulfill the condition.

Conditions can be defined with OR relation or as function. Learn more about conditions here.

view

Type: string

vue

<FormStep view="alt" ... />

The name of the view to be used for the component. If undefined the default view will be used.

Learn more about views here.

addClass

Type: array|object|string

vue

<FormStep :add-class="{
  classname: 'class-value',
  classname: ['class-value'],
  classname: [{'class-value': true}],
}" ... />

Adds classes to any of FormStep component's class names. Classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue

<FormStep :add-class="(form$) => ({
  classname: [
    { 'class-value': form$.el$('other_field')?.value === 'some_value' }
  ],
})" ... />

Learn more about adding classes here.

removeClass

Type: array|object

vue

<FormStep :remove-class="{
  classname: ['class-value-1', 'class-value-2']
}" ... />

Removes classes from any of FormStep component's class names. The classes to be removed must be listed in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue

<FormStep :remove-class="(form$) => ({
  classname: form$.el$('other_field')?.value === 'some_value'
    ? ['class-value-1', 'class-value-2']
    : [],
})" ... />

Learn more about removing classes here.

replaceClass

Type: object

vue

<FormStepElement :replace-class="{
  classname: {
    'from-class': 'to-class',
    'from-class': ['to-class'],
    'from-class': [{'to-class': true}],
  }
}" ... />

Replaces the classes of any class names of FormStep component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string or an array. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue

<FormStep :replace-class="(form$) => ({
  classname: form$.el$('other_field')?.value === 'some_value' ? {
    'from-class': 'to-class'
  } : {},
})" ... />

Learn more about replacing classes here.

overrideClass

Type: array|object|string

vue

<FormStep :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any of FormStep component's class names. The classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue

<FormStep :override-class="(form$) => (form$.el$('other_field')?.value === 'some_value' ? {
  classname: 'class-value'
} : {})" ... />

Learn more about overriding classes here.

Properties

All the data, computed and inject properties of the component.

step$

Type: FormStep
Group: computed

The step's component.

stepLabel

Type: string|Component
Default: null
Group: data

The label of the step.

index

Type: number
Group: computed

Index of this step among the other steps which are not hidden by unmet conditions.

isFirst

Type: boolean
Group: computed

Whether the step is the first.

isLast

Type: boolean
Group: computed

Whether the step is the first.

active

Type: boolean
Default: false
Group: data

Whether the step is active.

elements$

Type: object
Group: computed

The form elements' components.

steps$

Type: FormSteps
Group: computed

The parent FormSteps component.

children$

Type: object
Group: computed

The elements' components in the step.

done

Type: boolean
Group: computed

Whether the step is done (completed, validated has no invalid or pending elements).

completed

Type: boolean
Default: false
Group: data

Whether the step is completed.

validated

Type: boolean
Group: computed

Whether all the elements in the step were already validated at least once.

invalid

Type: boolean
Group: computed

Whether the step has any invalid elements.

pending

Type: boolean
Group: computed

Whether the step has any pending elements.

debouncing

Type: boolean
Group: computed

Whether the step has any debouncing elements.

busy

Type: boolean
Group: computed

Whether the step has any busy elements.

available

Type: boolean
Group: computed

Whether no conditions are defined or they are all fulfilled.

visible

Type: boolean
Group: computed

Whether the step should be visible.

isDisabled

Type: boolean
Default: true
Group: data

Whether the step is disabled.

Size

Type: string
Group: inject

The size of the component.

View

Type: string
Group: computed

The name of the resolved view for the component. This one should be used to determine the component's view in class functions.

template

Type: object
Group: computed

The component's template.

classes

Type: object
Group: computed

The component's classes.

theme

Type: object
Group: inject

The global theme object, which contains all the default templates and classes.

form$

Type: Vueform
Group: inject

The root form's component.

Methods

The methods of the component.

select

Returns: void

Deactivate all other steps and set the current one as active.

complete

Returns: void

Complete the step.

uncomplete

Returns: void

Uncomplete the step.

disable

Returns: void

Disable the step.

enable

Returns: void

Enable the step.

on

Arguments:
- {string} event* - name of the event to listen for
- {function} callback* - callback to run when the event is triggered
Returns: void

Adds a listener for an event.

off

Arguments:
- {string} event* - name of the event to remove
Returns: void

Removes all listeners for an event.

fire

Arguments:
- {any} args - list of arguments to pass over to the event callback
Returns: void

Fires and emits an event.

validate

Returns: Promise

Validate all elements within the step (async).

activate

Returns: void

Activate the step.

deactivate

Returns: void

Deactivate the step.

Events

Events emitted by the component. You can subscribe to them using regular @{eventName} listener in inline components or by using on(event, callback) method.

activate

Triggered when the step becomes active.

inactivate

Triggered when the step becomes inactive.

enable

Triggered when the step becomes enabled.

disable

Triggered when the step becomes disabled.

complete

Triggered when the step becomes completed.

Slots

The slots of the component.

default

Renders the label for the step.

FormStep ​

Basic Usage ​

Options ​

labels ​

buttons ​

elements ​

name ​

label ​

conditions ​

view ​

addClass ​

removeClass ​

replaceClass ​

overrideClass ​

Properties ​

step$ ​

stepLabel ​

index ​

isFirst ​

isLast ​

active ​

elements$ ​

steps$ ​

children$ ​

done ​

completed ​

validated ​

invalid ​

pending ​

debouncing ​

busy ​

available ​

visible ​

isDisabled ​

Size ​

View ​

template ​

classes ​

theme ​

form$ ​

Methods ​

select ​

complete ​

uncomplete ​

disable ​

enable ​

on ​

off ​

fire ​

validate ​

activate ​

deactivate ​

Events ​

activate ​

inactivate ​

enable ​

disable ​

complete ​

Slots ​

default ​

FormStep

Basic Usage

Options

labels

buttons

elements

name

label

conditions

view

addClass

removeClass

replaceClass

overrideClass

Properties

step$

stepLabel

index

isFirst

isLast

active

elements$

steps$

children$

done

completed

validated

invalid

pending

debouncing

busy

available

visible

isDisabled

Size

View

template

classes

theme

form$

Methods

select

complete

uncomplete

disable

enable

on

off

fire

validate

activate

deactivate

Events

activate

inactivate

enable

disable

complete

Slots

default