Yii2-FormWizard (v1.0)



A Yii2 plugin used for creating stepped form or form wizard using yii\widgets\ActiveForm and \yii\db\ActiveRecord, it uses smart wizard library for creating the form interface that uses 3 builtin and 2 extra themes, moreover you can also create your own customized theme too.

Note : It uses limited features of the jquery plugin SmartWizard that suite the needs of the ActiveForm validation so not all options in the javascript plugin library are allowed to be changed or customized from within this plugin.

External Libraries Used

How do I get set up?

use composer to install the extension

php composer.phar require  buttflattery/yii2-formwizard "@dev" 

or add into the composer.json file under require section


Available Options

Widget options

  • wizardContainerId (string): Id of the main container for the wizard.
  • formOptions (array): specify the ActiveForm properties.
  • labelNext : Next button label, default value Next.
  • labelPrev : Previous button label, default value Previous.
  • labelFinish : Finish button label, default value Finish.
  • classNext : css classes for the button Next, default btn btn-info.
  • classPrev : css classes for the button Previous, default btn btn-info.
  • classFinish : css classes for the button Finish, default btn btn-success.
  • steps (array) : An array of the steps(array), the steps can have models dedicated to each step, or a single model for all steps. Following options are recognized when specifying a step.

    • model (object) : The \yii\model\ActiveRecord model object to create step fields.
    • title (string) : The title of the step to be displayed inside the step Tab.
    • description (string) : The short description for the step.
    • formInfoText (text) : The text to be displayed on the top of the form fields inside the step.
    • fieldConfig (array) : This option is used mainly to customize the form fields for the step. 3 options are recognized inside the fieldConfig, 2 of them are except and only. See below for the details

      • except (array) : List of fields that should not be populated in the step or should be ignored, for example


        By default all the attributes that are safe to load value are populated, and the id or primary_key is ignored by default.

      • only (array) : list of the fields that should be populated for the step, only the fields specified in the list will be available and all other fields will be ignored.

      Apart from the above options the fieldConfig recognizes a special option specific to every field separately when customizing a field, for example you can specify a class to a field named username in the form like below.


      You should specify the field name of the model and its customization option settings in form of name=>value pairs. The following special options can be used when specifying the form/model field_name.

      • options (array)
      • containerOptions (array)
      • template (string)
      • labelOptions (array)
      • widget (string)


      • options (array) : You can specify the HTML attributes (name-value pairs) for the field.


        All those special options that are recognized by the

        can be used with-in the options option. The following 2 options are specially recognized by this widget when used with-in the options.

        • type (string): The type of the form field to be created, this can be text, dropdown,checkbox, radio or textarea. Default value for this option is text.

        • itemsList (string/array) : This option can be used with a dropdown, checkboxList or radioList. It is used in combination of the the option type. If you provide the itemsList an array and use the 'type'=>'checkbox' , it will call checkboxList(), and a checkbox() if you provide string, same goes for the radioList and radio.

      • lableOptions (array): The HTML and special options for customizing the field label, you can use the following settings

        • label (string): The label text.
        • options (array) : The HTML attributes (name-value pairs) for the label.
      • template (string) : The template used for the field the default value used is {label}\n{input}\n{hint}\n{error}.
      • containerOptions (array) : HTML atrtibutes for the cotnainer tag used as name=>value pairs.
      • widget : This option can be used if you want to use a widget instead of the the default fields, you can specify the widget class name 'widget'=>widget::class, and the options for the widget will be provided in the options option.

Widget Plugin (SmartWizard) Options

Only the following options of the plugin SmartWizard are allowed to be customized

  • theme : name of the theme to be used, there are mainly 6 themes supported by the plugin
    • default : const THEME_DEFAULT
    • dots : const THEME_DOTS
    • arrows : const THEME_ARROWS
    • circles : const THEME_CIRCLES
    • material : const THEME_MATERIAL
    • material-v : const THEME_MATERIAL_V
  • transitionEffect (string) : The effect used when sliding the step it can be one of the
    • none
    • slide
    • fade
  • showStepURLhash (boolean) : Show url hash based on step, default false.
  • useURLHash (boolean) : Enable selection of the step based on url hash, default value is false.
  • toolbarPosition : Position of the toolbar (none, top, bottom, both), default value top.
  • toolbarExtraButtons : Specify the extra buttons and its events to show on toolbar.
  • markDoneSteps (boolean) : Make already visited steps as done, default value is true.
  • markAllPreviousStepsAsDone (boolean): When a step selected by url hash, all previous steps are marked done, default value is true.
  • removeDoneStepOnNavigateBack (boolean) : While navigate back done step after active step will be cleared, default value is false.
  • enableAnchorOnDoneStep (boolean) : Enable/Disable the done steps navigation, default value is true.

Who do I talk to?