{"id":17753091,"url":"https://github.com/adrianvillamayor/wizard-js","last_synced_at":"2025-07-29T22:15:37.670Z","repository":{"id":51446346,"uuid":"402367518","full_name":"AdrianVillamayor/Wizard-JS","owner":"AdrianVillamayor","description":"A lightweight wizard UI component that supports accessibility and HTML5 in JavaScript Vanilla.","archived":false,"fork":false,"pushed_at":"2024-10-29T14:16:32.000Z","size":239,"stargazers_count":54,"open_issues_count":1,"forks_count":13,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-19T07:29:38.313Z","etag":null,"topics":["commonjs","eslint","esm","javascript","js","lightweight","npm","npm-package","vanilla-javascript","webpack","wizard","wizard-js","wizard-steps"],"latest_commit_sha":null,"homepage":"https://adrianvillamayor.github.io/Wizard-JS/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AdrianVillamayor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-02T09:44:47.000Z","updated_at":"2025-06-19T07:27:41.000Z","dependencies_parsed_at":"2024-12-16T20:32:36.555Z","dependency_job_id":null,"html_url":"https://github.com/AdrianVillamayor/Wizard-JS","commit_stats":{"total_commits":133,"total_committers":2,"mean_commits":66.5,"dds":0.007518796992481258,"last_synced_commit":"09aaa4e86684e207689a014de526a061bf9095a6"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/AdrianVillamayor/Wizard-JS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrianVillamayor%2FWizard-JS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrianVillamayor%2FWizard-JS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrianVillamayor%2FWizard-JS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrianVillamayor%2FWizard-JS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdrianVillamayor","download_url":"https://codeload.github.com/AdrianVillamayor/Wizard-JS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrianVillamayor%2FWizard-JS/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266235409,"owners_count":23897179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commonjs","eslint","esm","javascript","js","lightweight","npm","npm-package","vanilla-javascript","webpack","wizard","wizard-js","wizard-steps"],"created_at":"2024-10-26T13:07:51.968Z","updated_at":"2025-07-21T03:32:30.751Z","avatar_url":"https://github.com/AdrianVillamayor.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build and Lint](https://github.com/AdrianVillamayor/Wizard-JS/actions/workflows/main.yml/badge.svg)](https://github.com/AdrianVillamayor/Wizard-JS/actions/workflows/main.yml)\n![Badge-glow](https://img.shields.io/badge/WizardJS-v2.0.3-blue?style=flat-square)\n[![jsDelivr hits (GitHub)](https://data.jsdelivr.com/v1/package/gh/AdrianVillamayor/Wizard-JS/badge)](https://www.jsdelivr.com/package/gh/AdrianVillamayor/Wizard-JS)\n![GitHub repo size](https://img.shields.io/github/repo-size/AdrianVillamayor/Wizard-JS?style=flat-square)\n\n# Wizard-JS\n\nA lightweight wizard UI component that supports accessibility and HTML5 in Vanilla JavaScript.\n\n## Features\n\n- Supports accessibility (ARIA-compliant).\n- Fully customizable wizard steps and navigation.\n- Works with both ES modules and CommonJS.\n- Built-in form validation and control.\n- **New Features:**\n  - Conditional required fields using `data-require-if` attribute.\n  - Dynamic required fields with `on-active-required` class.\n  - Customizable validation highlighting.\n\n\n## Table of Contents\n\n- [Wizard-JS](#wizard-js)\n  - [Features](#features)\n  - [Table of Contents](#table-of-contents)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [CommonJS](#commonjs)\n    - [ES Modules](#es-modules)\n    - [Example HTML for Wizard](#example-html-for-wizard)\n    - [Launch the Wizard](#launch-the-wizard)\n    - [Restart the Wizard](#restart-the-wizard)\n    - [Update the Wizard](#update-the-wizard)\n    - [Lock and Unlock the Wizard](#lock-and-unlock-the-wizard)\n  - [Form Validation](#form-validation)\n    - [Required Fields](#required-fields)\n    - [Conditionally Required Fields](#conditionally-required-fields)\n    - [Dynamic Required Fields](#dynamic-required-fields)\n    - [Custom Validation Highlighting](#custom-validation-highlighting)\n  - [HTML Attributes](#html-attributes)\n    - [Data Title Attribute `[data-wz-title]`](#data-title-attribute-data-wz-title)\n    - [Data Require If Attribute `[data-require-if]`](#data-require-if-attribute-data-require-if)\n  - [Config Wizard](#config-wizard)\n    - [i18n Options](#i18n-options)\n  - [Events Management](#events-management)\n    - [Wizard Ready Event](#wizard-ready-event)\n    - [Wizard Update Event](#wizard-update-event)\n    - [Lock and Unlock Events](#lock-and-unlock-events)\n    - [Navigation Events](#navigation-events)\n    - [Validation Error Event](#validation-error-event)\n    - [Form Submission and Wizard Completion Events](#form-submission-and-wizard-completion-events)\n    - [Reset Event](#reset-event)\n  - [Demo](#demo)\n  - [Contributing](#contributing)\n  - [License](#license)\n    - [Thanks for your help! 🎉](#thanks-for-your-help-)\n\n## Installation\n\nYou can install the package via [npm](https://www.npmjs.com/package/@adrii_/wizard-js):\n\n```bash\nnpm install @adrii_/wizard-js\n```\n\nFor \u003ca href=\"https://www.jsdelivr.com/package/gh/AdrianVillamayor/Wizard-JS\" target=\"_blank\"\u003eCDN\u003c/a\u003e usage:\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/gh/AdrianVillamayor/Wizard-JS@2.0.3/dist/main.min.css\"\u003e\n\n\u003cscript src=\"https://cdn.jsdelivr.net/gh/AdrianVillamayor/Wizard-JS@2.0.3/dist/index.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\n### CommonJS\n\n```javascript\nconst Wizard = require('@adrii_/wizard-js');\nconst myWizard = new Wizard({\n  /* your configuration here */\n});\n\nmyWizard.init();\n```\n\n### ES Modules\n\n```javascript\nimport Wizard from '@adrii_/wizard-js';\nconst myWizard = new Wizard({\n  /* your configuration here */\n});\n\nmyWizard.init();\n```\n\n### Example HTML for Wizard\n\nFor content-only wizards:\n\n```html\n\u003cdiv class=\"wizard\"\u003e\n    \u003caside class=\"wizard-content container\"\u003e\n        \u003cdiv class=\"wizard-step\"\u003e\n            \u003c!-- Step content --\u003e\n        \u003c/div\u003e\n        \u003c!-- More steps --\u003e\n    \u003c/aside\u003e\n\u003c/div\u003e\n```\n\nFor wizards with form purpose, it manages the required fields and validates them:\n\n```html\n\u003cform class=\"wizard\" method=\"POST\"\u003e\n    \u003caside class=\"wizard-content container\"\u003e\n        \u003cdiv class=\"wizard-step\"\u003e\n            \u003cinput type=\"text\" name=\"name\" class=\"required\" placeholder=\"Enter a short campaign name\"\u003e\n        \u003c/div\u003e\n        \u003c!-- More steps --\u003e\n    \u003c/aside\u003e\n\u003c/form\u003e\n```\n\n### Launch the Wizard\n\nTo **launch** the wizard:\n\n```javascript\nlet args = {\n    \"wz_class\": \".wizard\",\n    \"wz_nav_style\": \"dots\",\n    \"wz_button_style\": \".btn .btn-sm .mx-3\",\n    \"wz_ori\": \"vertical\",\n    \"buttons\": true,\n    \"navigation\": 'buttons',\n    \"finish\": \"Save!\"\n};\n\nconst wizard = new Wizard(args);\n\nwizard.init();\n```\n\n### Restart the Wizard\n\nTo **restart** the wizard:\n\n```javascript\nwizard.reset();\n```\n\n### Update the Wizard\n\nTo **update** the wizard, deleting or adding steps:\n\n```javascript\nwizard.update();\n```\n\n### Lock and Unlock the Wizard\n\nTo **lock** the wizard at a specific step:\n\n```javascript\nwizard.lock();\n```\n\nTo **unlock** the wizard:\n\n```javascript\nwizard.unlock();\n```\n\n## Form Validation\n\nWizard-JS includes built-in form validation for required fields.\n\n### Required Fields\n\nTo mark an input as required, add the `required` attribute or the `required` class:\n\n```html\n\u003cinput type=\"text\" name=\"email\" required\u003e\n\u003c!-- or --\u003e\n\u003cinput type=\"text\" name=\"email\" class=\"required\"\u003e\n```\n\n### Conditionally Required Fields\n\nYou can make fields conditionally required based on the value of another field using the `data-require-if` attribute.\n\nThe format is `data-require-if=\"fieldID:requiredValue\"`.\n\n```html\n\u003cinput type=\"checkbox\" id=\"subscribe\" name=\"subscribe\"\u003e\n\n\u003cinput type=\"email\" name=\"email\" data-require-if=\"subscribe:true\" placeholder=\"Enter your email\"\u003e\n```\n\nIn this example, the email field becomes required if the checkbox with id `subscribe` is checked (`true`).\n\n### Dynamic Required Fields\n\nUse the `on-active-required` class to mark fields that become required only when the step is active.\n\n```html\n\u003cinput type=\"text\" name=\"username\" class=\"on-active-required\" placeholder=\"Enter your username\"\u003e\n```\n\n### Custom Validation Highlighting\n\nYou can customize the validation highlighting behavior:\n\n- `highlight`: Set to `true` to enable highlighting invalid fields.\n- `highlight_time`: Duration (in milliseconds) to display the highlight. Default is `1000`.\n- `highlight_type`: An object to define the classes for different highlight types.\n\nExample:\n\n```javascript\nlet args = {\n    /* Other configurations */\n    \"highlight\": true,\n    \"highlight_time\": 1500,\n    \"highlight_type\": { error: \"error\", warning: \"warning\", success: \"success\", info: \"info\" }\n};\n```\n\n## HTML Attributes\n\n### Data Title Attribute `[data-wz-title]`\n\nSet the step title for the navigation. If left blank, the system will automatically add `Step + step number` as the title.\n\n```html\n\u003cdiv class=\"wizard-step\" data-wz-title=\"Configuration\"\u003e\n    \u003c!-- Step content --\u003e\n\u003c/div\u003e\n```\n\n### Data Require If Attribute `[data-require-if]`\n\nDefine conditional required fields based on another field's value.\n\n```html\n\u003cinput type=\"email\" name=\"email\" data-require-if=\"subscribe:true\" placeholder=\"Enter your email\"\u003e\n```\n\n## Config Wizard\n\nOptions allowing you to modify the behavior and actions:\n\n| Parameter         | Type    | Default                                                                    | Definition / Value                                             |\n| ----------------- | ------- | -------------------------------------------------------------------------- | -------------------------------------------------------------- |\n| `wz_class`        | String  | `.wizard`                                                                  | Wizard main container target                                   |\n| `wz_ori`          | String  | `.horizontal`                                                              | Wizard orientation (`.horizontal`, `.vertical`)                |\n| `wz_nav`          | String  | `.wizard-nav`                                                              | Navigation container class                                     |\n| `wz_nav_style`    | String  | `dots`                                                                     | Style of navigation steps (`dots`, `tabs`, `progress`)         |\n| `wz_content`      | String  | `.wizard-content`                                                          | Body container class                                           |\n| `wz_buttons`      | String  | `.wizard-buttons`                                                          | Action button container class                                  |\n| `wz_button`       | String  | `.wizard-btn`                                                              | Class of Previous, Next, and Finish action buttons             |\n| `wz_button_style` | String  | `.btn`                                                                     | Basic button style                                             |\n| `wz_step`         | String  | `.wizard-step`                                                             | Class for both nav and body steps                              |\n| `wz_form`         | String  | `.wizard-form`                                                             | Class of the form that contains the wizard                     |\n| `wz_next`         | String  | `.next`                                                                    | Class of Next action button                                    |\n| `wz_prev`         | String  | `.prev`                                                                    | Class of Prev action button                                    |\n| `wz_finish`       | String  | `.finish`                                                                  | Class of Finish action button                                  |\n| `wz_highlight`    | String  | `.highlight-error`                                                         | Class for highlights when validation errors occur              |\n| `current_step`    | Number  | `0`                                                                        | Active wizard step                                             |\n| `steps`           | Number  | `0`                                                                        | Number of wizard steps                                         |\n| `highlight_time`  | Number  | `1000`                                                                     | Display time for validation highlight (in milliseconds)        |\n| `navigation`      | String  | `all`                                                                      | Navigation mode (`buttons`, `nav`, `all`)                      |\n| `buttons`         | Boolean | `true`                                                                     | Show or hide the action buttons                                |\n| `nav`             | Boolean | `true`                                                                     | Show or hide the header navigation                             |\n| `highlight`       | Boolean | `true`                                                                     | Enable or disable field highlighting on validation errors      |\n| `next`            | String  | `Next`                                                                     | Text for the Next button                                       |\n| `prev`            | String  | `Prev`                                                                     | Text for the Prev button                                       |\n| `finish`          | String  | `Submit`                                                                   | Text for the Finish button                                     |\n| `bubbles`         | Boolean | `false`                                                                    | Enable or disable event bubbling for custom events             |\n| `highlight_type`  | Object  | `{ error: \"error\", warning: \"warning\", success: \"success\", info: \"info\" }` | Classes for different validation highlight effects             |\n| `i18n`            | Object  | Various                                                                    | Internationalization messages for errors, titles, and warnings |\n\n### i18n Options\n\nThe `i18n` object allows you to define custom error messages for different wizard actions:\n\n- `empty_wz`: \"No item has been found with which to generate the Wizard.\"\n- `empty_nav`: \"Nav does not exist or is empty.\"\n- `empty_content`: \"Content does not exist or is empty.\"\n- `empty_html`: \"Undefined or null content cannot be added.\"\n- `empty_update`: \"Nothing to update.\"\n- `no_nav`: \"Both the nav and the buttons are disabled, there is no navigation system.\"\n- `form_validation`: \"One or more of the form fields are invalid.\"\n- `diff_steps`: \"Discordance between the steps of nav and content.\"\n- `random`: \"There has been a problem, check the configuration and use of the wizard.\"\n- `already_defined`: \"This item is already defined.\"\n- `title`: \"Step\" (used for default step titles if not specified in the HTML).\n\n## Events Management\n\nWizard-JS provides several events to help you manage and respond to user interactions.\n\n### Wizard Ready Event\n\nTo identify when the wizard is fully generated and loaded.\n\n```javascript\ndocument.addEventListener(\"wz.ready\", function (e) {\n    console.log(`Target:`, e.detail.target); // .wizard\n    console.log(`DOM Element:`, e.detail.elem); // DOM element\n});\n```\n\n### Wizard Update Event\n\nTriggered when the wizard is updated.\n```javascript\nlet wz_class = \".wizard\";\nlet $wz_doc = document.querySelector(wz_class)\n```\n\n```javascript\n$wz_doc.addEventListener(\"wz.update\", function (e) {\n    console.log(`Target:`, e.detail.target);\n    console.log(`DOM Element:`, e.detail.elem);\n});\n```\n\n### Lock and Unlock Events\n\nWhen the wizard is locked:\n\n```javascript\n$wz_doc.addEventListener(\"wz.lock\", function (e) {\n    alert(\"Wizard is locked\");\n});\n```\n\nWhen the wizard is unlocked:\n\n```javascript\n$wz_doc.addEventListener(\"wz.unlock\", function (e) {\n    alert(\"Wizard is unlocked\");\n});\n```\n\n### Navigation Events\n\nMoving to the previous step:\n\n```javascript\n$wz_doc.addEventListener(\"wz.btn.prev\", function (e) {\n    alert(\"Previous Step\");\n});\n```\n\nMoving to the next step:\n\n```javascript\n$wz_doc.addEventListener(\"wz.btn.next\", function (e) {\n    alert(\"Next Step\");\n});\n```\n\nNavigating forward with the navbar:\n\n```javascript\n$wz_doc.addEventListener(\"wz.nav.forward\", function (e) {\n    alert(\"Forward Navigation\");\n});\n```\n\nNavigating backward with the navbar:\n\n```javascript\n$wz_doc.addEventListener(\"wz.nav.backward\", function (e) {\n    alert(\"Backward Navigation\");\n});\n```\n\n### Validation Error Event\n\nTriggered when there is an error validating the data of the active form step.\n\n```javascript\n$wz_doc.addEventListener(\"wz.error\", function (e) {\n    console.log(`ID:`, e.detail.id); // form_validation\n    console.log(`Message:`, e.detail.msg); // Form validation message\n    console.log(`Target:`, e.detail.target); // Array of invalid elements\n});\n```\n\n### Form Submission and Wizard Completion Events\n\nIf it is a form, at the end it will fire the following event:\n\n```javascript\n$wz_doc.addEventListener(\"wz.form.submit\", function (e) {\n    alert(\"Form Submitted\");\n});\n```\n\nIf it is not a form, at the end it will fire the following event:\n\n```javascript\n$wz_doc.addEventListener(\"wz.end\", function (e) {\n    alert(\"Wizard is finished\");\n});\n```\n\n### Reset Event\n\nWhen the wizard is restarted:\n\n```javascript\n$wz_doc.addEventListener(\"wz.reset\", function (e) {\n    alert(\"Wizard has restarted\");\n});\n```\n\n## Demo\n\nTry it on CodePen:\n\n[![Codepen](https://user-images.githubusercontent.com/29653964/116972608-8f6bca80-acbb-11eb-98c1-8a3b19705de1.png)](https://codepen.io/adrianvillamayor/pen/VwWPVME)\n\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## License\n\n[MIT](https://github.com/AdrianVillamayor/Wizard-JS/blob/main/LICENSE)\n### Thanks for your help! 🎉\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianvillamayor%2Fwizard-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadrianvillamayor%2Fwizard-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianvillamayor%2Fwizard-js/lists"}