vue-form-wizard/docs/README.md

vue-form-wizard

A dynamic form wizard to split your forms easier

Vue-form-wizard is a vue based component with no external depenendcies which simplifies tab wizard management and allows you to focus on the functional part of your app rather than wasting time on details. Just forget about id's, external scripts and jQuery dependencies

Demos

Basic demo

Other demos:

• Squared steps
• Tabbed steps
• Step index Start at any step. Note: start-index is zero-based and the count starts at 0
• Custom button and title text
• Custom title slot
• Customized buttons with slots Replace stuff you don't like
• Call a function before tab switch
• Complete form example integrated with vue-form-generator
• Element UI form integration
• Vue router integration You can place a router-view inside the wizard and have a separate page per tab. A route prop must be passed to the tabs you want to handle certain tabs
• Async validation with error message before-change prop can accept a promise that is resolved with true which will execute the promise before switching to another step/tab (NOTE: This feature is not present in the npm package yet)

There is also a Playground where you can test stuff out right here in the browser!

Usage

NPM

npm install vue-form-wizard

Direct script include

Download the css and js files from dist folder or reference them directly from github (check jsfiddle links)

<link rel="stylesheet" href="https://unpkg.com/vue-form-wizard/dist/vue-form-wizard.min.css">
<script src="https://unpkg.com/vue-form-wizard/dist/vue-form-wizard.js"></script>

Component registration

//global registration
import VueFormWizard from 'vue-form-wizard'
import 'vue-form-wizard/dist/vue-form-wizard.min.css'
Vue.use(VueFormWizard)

//local registration
import {FormWizard, TabContent} from 'vue-form-wizard'
import 'vue-formwizard/dist/vue-form-wizard.min.css'
//component code
components: {
  FormWizard,
  TabContent
}

Template usage

<form-wizard>
  <tab-content title="Personal details">
    My first tab content
  </tab-content>
  <tab-content title="Additional Info">
      My second tab content
   </tab-content>
   <tab-content title="Last step">
     Yuhuuu! This seems pretty damn simple
   </tab-content>
</form-wizard>

Props

Form Wizard props

props: {
  title: {
    type: String,
    default: 'Awesome Wizard'
  },
  subtitle: {
    type: String,
    default: 'Split a complicated flow in multiple steps'
  },
  nextButtonText: {
    type: String,
    default: 'Next'
  },
  backButtonText: {
    type: String,
    default: 'Back'
  },
  finishButtonText: {
    type: String,
    default: 'Finish'
  },
  /***
  *  Sets validation (on/off) for back button. By default back button ignores validation
  */
  validateOnBack: Boolean,
  /***
  * Applies to text, border and circle
  */
  color: {
    type: String,
    default: '#e74c3c' //circle, border and text color
  },
  /***
  *  Is set to current step and text when beforeChange function fails 
  */
  errorColor: {
    type: String,
    default: '#8b0000'
  },
  /**
  * Can take one of the following values: 'circle|square|tab`
  */
  shape: {
    type: String,
    default: 'circle'
  },
  /**
  * name of the transition when transition between steps
  */
  transition: {
    type: String,
    default: '' //name of the transition when transition between steps
  },
  /***
  * Index of the initial tab to display
  */
  startIndex: {
    type: Number,
    default: 0
  }
}

Tab content props

props: {
  title: {
    type: String,
    default: ''
  },
  /***
   * Icon name for the upper circle corresponding to the tab
   * Supports themify icons only for now.
   */
  icon: {
    type: String,
    default: ''
  },
  /***
   * Function to execute before tab switch. Return value must be boolean
   * If the return result is false, tab switch is restricted
   */
  beforeChange: {
    type: Function
  }
}

Events

Vue-form-wizard emits certain events when certain actions happen inside the component. The events can be noticed in some of the demos and especially in the async validation demo

• on-complete Called when the finish button is clicked and the before-change for the last step (if present) was executed. No params are sent together with this event. this.$emit('on-complete')
• on-loading Called whenever an async before-change is executed. This event is emitted before executing before-change and after finishing execution of before-change method. on-loading is emitted together with a Boolean value. this.$emit('on-loading', value)
• on-validate Called whenever the execution of a before-change method is completed. The event sends along a Boolean which represents the validation result as well as an int with te tab index. this.$emit('on-validate', validationResult, this.activeTabIndex)
• on-error Called when before-change is a promised and is rejected with a message. The message is passed along this.$emit('on-error', error) See async validation fiddle

Slots

• Default - Used for tab-contents
• title - Upper title section including sub-title
• prev - Previous button content (no need to worry about handling the button functionality)
• next - Next button content
• finish - Finish button content

Contribution

1. Fork the repo
2. run npm install
3. npm run dev for launching the dev example
4. After making your changes make sure to pull the changes from the source repo to avoid conflicts
5. npm run build to generate the new js and css bundles
6. Commit your changes + the js and css bundles so it's easy to test them right away in fiddles, codepen etc
7. Open a Pull Request. For more information refer to github forking workflow

Playground

Simple

<script v-pre type="text/x-template" id="simpledemo"> My first tab content My second tab content Yuhuuu! This seems pretty damn simple <script> Vue.use(VueFormWizard) export default { methods: { onComplete: function(){ alert('Yay. Done!'); } } } </script>

</script>

Square steps

<script v-pre type="text/x-template" id="squaredsteps"> My first tab content My second tab content Yuhuuu! This seems pretty damn simple <script> Vue.use(VueFormWizard) export default { methods: { onComplete: function(){ alert('Yay. Done!'); } } } </script>

</script>

Tabbed steps

<script v-pre type="text/x-template" id="tabbedsteps"> My first tab content My second tab content Yuhuuu! This seems pretty damn simple <script> Vue.use(VueFormWizard) export default { methods: { onComplete: function(){ alert('Yay. Done!'); } } } </script>

</script>

Start from a specific index

<script v-pre type="text/x-template" id="startindex"> My first tab content My second tab content Yuhuuu! This seems pretty damn simple <script> Vue.use(VueFormWizard) export default { methods: { onComplete: function(){ alert('Yay. Done!'); } } } </script>

</script>

Custom button and title text

<script v-pre type="text/x-template" id="customtext"> My first tab content My second tab content Yuhuuu! This seems pretty damn simple <script> Vue.use(VueFormWizard) export default { methods: { onComplete: function(){ alert('Yay. Done!'); } } } </script>

</script>

Replace buttons and title with Slots

<script v-pre type="text/x-template" id="customslots">

This will replace my whole title

My first tab content My second tab content Yuhuuu! This seems pretty damn simple Back Next Finish <script> Vue.use(VueFormWizard) export default { methods: { onComplete: function(){ alert('Yay. Done!'); } } } </script>

</script>

Call a function before tab switch

<script v-pre type="text/x-template" id="callfunction"> My first tab content My second tab content Yuhuuu! This seems pretty damn simple <script> Vue.use(VueFormWizard) export default { methods: { onComplete: function(){ alert('Yay. Done!'); }, beforeTabSwitch: function(){ alert("This is called before switchind tabs") return true; } }, } </script>

</script>

Async validation

<script v-pre type="text/x-template" id="asyncvalidation"> First tab Second tab Third tab

{{errorMsg}}

<style> span.error{ color:#e74c3c; font-size:20px; display:flex; justify-content:center; } </style> <script> Vue.use(VueFormWizard) export default { data(){ return { loadingWizard: false, errorMsg: null, count: 0 } }, methods: { onComplete: function(){ alert('Yay. Done!'); }, setLoading: function(value) { this.loadingWizard = value }, handleValidation: function(isValid, tabIndex){ console.log('Tab: '+tabIndex+ ' valid: '+isValid) }, handleErrorMessage: function(errorMsg){ this.errorMsg = errorMsg }, validateAsync:function() { return new Promise((resolve, reject) => { setTimeout(() => { if(this.count < 1){ this.count ++ reject('This is a custom validation error message. Click next again to get rid of the validation') }else{ this.count = 0 resolve(true) } }, 1000) }) }, } } </script>

</script>

Element UI integration

<script v-pre type="text/x-template" id="elementui"> Second tab Yuhuuu! This seems pretty damn simple Back Next Finish <script> Vue.use(VueFormWizard) export default { data() { return { formInline: { user: '', region: '' }, rules: { user: [{ required: true, message: 'Please input Activity name', trigger: 'blur' }, { min: 3, max: 5, message: 'Length should be 3 to 5', trigger: 'blur' }], region: [{ required: true, message: 'Please select Activity zone', trigger: 'change' }], } } }, methods: { onComplete: function() { alert('Yay. Done!'); }, validateFirstStep() { return new Promise((resolve, reject) => { this.$refs.ruleForm.validate((valid) => { resolve(valid); }); }) } } } </script>

</script>