# inertia-bootstrap-forms A Vue 3 component library for building Bootstrap‑styled forms inside **Laravel + Inertia.js** applications. Every input component binds itself automatically to an [Inertia `useForm`](https://inertiajs.com/forms) instance through a `` wrapper, so you stop wiring up `v-model`, error classes, and field names by hand for every form. This package has been developed and maintained by **[Novin Vision](https://novinvision.com)** (شرکت **[نوین ویژن](https://novinvision.com)**), a team specialized in **[طراحی سایت](https://novinvision.com)** and **[web design](https://novinvision.com)**. # About Us Novin Vision focuses on building modern and practical web solutions for businesses and developers who want a reliable digital presence. The approach is simple: clean design, solid development, and results that can be used in real projects without complexity. If you want to learn more or get in touch, you can visit: https://novinvision.com ## License The use of this package is completely free. You are allowed to use it in personal and commercial projects without any restriction or payment. --- Built and maintained by **Novin Vision** ```vue
Name
Alias
Status
New Image
Description
``` --- ## Table of Contents 1. [Requirements](#requirements) 2. [Installation](#installation) 3. [Global Setup (required helpers)](#global-setup-required-helpers) 4. [Core Concepts](#core-concepts) 5. [Component Reference](#component-reference) - [FormContainer](#formcontainer) - [FormLabel](#formlabel) - [GroupControl](#groupcontrol) - [TextInput](#textinput) - [TextAreaInput](#textareainput) - [EmailInput](#emailinput) - [PasswordInput](#passwordinput) - [MobileInput](#mobileinput) - [TelInput](#telinput) - [AmountInput](#amountinput) - [QuantityInput](#quantityinput) - [MultiQuantityInput](#multiquantityinput) - [CheckboxInput](#checkboxinput) - [CheckboxButtonInput](#checkboxbuttoninput) - [CheckboxToggle](#checkboxtoggle) - [Select2Input](#select2input) - [PersianDatePickerInput](#persiandatepickerinput) - [RangeSliderInput](#rangesliderinput) - [StarRatingInput](#starratinginput) - [CaptchaInput](#captchainput) - [EditorInput](#editorinput) - [LocationInput](#locationinput) - [FileInput](#fileinput) - [SimpleUploader](#simpleuploader) - [DropzoneInput](#dropzoneinput) - [UppyInput](#uppyinput) - [SubmitButton](#submitbutton) 6. [Upload Endpoint Contract (backend)](#upload-endpoint-contract-backend) 7. [Styling & Theming](#styling--theming) 8. [TypeScript](#typescript) 9. [Known Limitations](#known-limitations) --- ## Requirements The package itself only ships the Vue components (plus a few smaller libraries that are already bundled into `dist/`). The following must exist in the **host** application: | Requirement | Why | |---|---| | Vue `^3.0` | The components are plain Vue 3 SFCs. | | `@inertiajs/vue3` `>2.0` | `FormContainer` calls Inertia's `useForm()` internally. | | Bootstrap 5 CSS (`.form-control`, `.btn`, `.input-group`, `.form-check`, CSS variables like `--bs-*`, etc.) | All markup/classes assume Bootstrap 5 is loaded. | | `dropzone` `^6.0.0-beta.2` | Only needed if you use ``. | | `@tinymce/tinymce-vue` | Only needed if you use `` (TinyMCE). | | `@vue-leaflet/vue-leaflet` + `leaflet` | Only needed if you use ``. | | `vue-tel-input` | Only needed if you use ``. | | `vue3-persian-datetime-picker` | Only needed if you use ``. | | `maska` | Only needed if you use `` or `` (number masking). | | `axios` available globally as `window.axios` | Used internally by ``. Laravel's default `resources/js/bootstrap.js` already does this (`window.axios = require('axios')`). | The following libraries are **already bundled inside `dist/`** and do **not** need to be installed separately: `vue3-bootstrap-components`, `choices.js`, `svelte-range-slider-pips`, `@uppy/core`, `@uppy/vue`, `@uppy/xhr-upload`. --- ## Installation ### 1. Install the package This package isn't necessarily on the public npm registry, so install it however it was distributed to you: ```bash # from a private/internal npm registry npm install inertia-bootstrap-forms # from a Git repository npm install git+https://github.com/novinvision/inertia-bootstrap-forms.git # from a local folder or tarball npm install file:../path/to/inertia-bootstrap-forms ``` ### 2. Install the peer libraries you actually need You don't have to install all of them — only the ones backing the components you use: ```bash npm install @inertiajs/vue3 dropzone @tinymce/tinymce-vue \ @vue-leaflet/vue-leaflet leaflet vue-tel-input \ vue3-persian-datetime-picker maska ``` ### 3. Import the package styles ```js // resources/js/app.js import 'inertia-bootstrap-forms/dist/style.css'; ``` ### 4. Register the components You can either import components individually (recommended, keeps the bundle small): ```vue ``` …or register everything globally once, in `app.js`: ```js import { createApp, h } from 'vue'; import { createInertiaApp } from '@inertiajs/vue3'; import * as InertiaBootstrapForms from 'inertia-bootstrap-forms'; import 'inertia-bootstrap-forms/dist/style.css'; createInertiaApp({ resolve: name => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')), setup({ el, App, props, plugin }) { const app = createApp({ render: () => h(App, props) }).use(plugin); Object.entries(InertiaBootstrapForms).forEach(([name, component]) => { if (name !== 'default') app.component(name, component); }); app.mount(el); }, }); ``` --- ## Global Setup (required helpers) Two components (`AmountInput`, `QuantityInput`) rely on globals that this package does **not** provide. You need to register them yourself in `app.js` before those components will work. ### `v-maska` directive `AmountInput` and `QuantityInput` use `v-maska` (from the [`maska`](https://www.npmjs.com/package/maska) package) to format numbers with thousand separators while typing. ```bash npm install maska ``` ```js import { vMaska } from 'maska/vue'; app.directive('maska', vMaska); ``` You can use any version/config of `maska` you like — the components only depend on the directive name (`v-maska`) and the `@maska` event payload (`event.detail.unmasked`), so feel free to follow Maska's own documentation for advanced masking options. ### `$number` global helper The same two components call `this.$number.toEnglish(...)` to convert localized (Persian/Arabic-Indic) digits typed by the user into plain English digits before storing them in the form. This helper is **not bundled** — you need to provide it as a global property. A minimal implementation that mirrors the digit conversion already used internally by `FormContainer` on submit: ```js // resources/js/plugins/number.js const persianDigits = ['۰','۱','۲','۳','۴','۵','۶','۷','۸','۹']; const arabicDigits = ['٠','١','٢','٣','٤','٥','٦','٧','٨','٩']; export default { install(app) { app.config.globalProperties.$number = { toEnglish(value) { if (value === null || value === undefined) return value; let str = value.toString(); persianDigits.forEach((d, i) => { str = str.replaceAll(d, i); }); arabicDigits.forEach((d, i) => { str = str.replaceAll(d, i); }); return str.replaceAll(',', ''); } }; } }; ``` ```js import NumberPlugin from './plugins/number'; app.use(NumberPlugin); ``` If you don't use `AmountInput` or `QuantityInput`, you can skip this section entirely. ### Optional: Font Awesome `CaptchaInput` renders a refresh icon using a Font Awesome class (`fal fa-sync-alt`, Pro "light" style). If you don't load Font Awesome Pro, the button still works — you just won't see the icon. Swap in your own icon via the component's markup if needed. --- ## Core Concepts ### `FormContainer` and the injected `form` `` wraps Inertia's `useForm()` and `provide()`s it to every descendant via Vue's `provide`/`inject`. All the field components below `inject` this `form` object and read/write `form[name]` automatically — that's the entire trick behind not having to wire `v-model` on every field yourself. ```vue ``` `FormContainer` props: | Prop | Type | Default | Description | |---|---|---|---| | `url` | String | `''` | Endpoint the form submits to. | | `method` | String | `'post'` | HTTP method passed to Inertia's `form.submit()`. | | `only` | Array | `[]` | Inertia partial-reload `only` option. | | `modelValue` | Object | `{}` | Initial data for the form (also works with `v-model`). | | `options` | Object | `{}` | Extra fields merged into the Inertia form state (e.g. defaults that aren't real inputs). | | `resetOnSuccess` | Boolean | `false` | Calls `form.reset()` automatically after a successful submit. | | `submitHandler` | Function | `null` | If provided, this function is called instead of the default Inertia submit flow — useful for custom submit logic (e.g. confirmation modals). | Events: `submit`, `reset`, `onStart`, `onFinish`, `onSuccess`, `onError`, `change`, `update:modelValue`. Slots: - default — scoped with `{ form, submit }`, the actual form fields. - `errors` — override the default error `` block. - `message` — override the default success `` block (shown when the backend response includes a `message` prop). Exposed methods (via template ref): `submit()`, `reset()`. Notable built-in behavior: on submit, `FormContainer` converts any Persian/Arabic-Indic digits present in the form's values to plain English digits before sending the request — handy for numeric fields typed with a Persian keyboard. ### Field naming & binding Every field component takes a `name` prop. As long as it lives inside a `` (or any component that injects a `form`), it automatically reads/writes `form[name]` — no manual `v-model` needed: ```vue ``` Validation errors are read from `form.errors[name]` and applied as Bootstrap's `is-invalid` class automatically. ### Grouped / repeated fields — `GroupControl` `` lets a *block* of fields write into a nested/indexed slice of the form data instead of the top level — useful for repeating rows (e.g. multiple bid items, multiple contacts, etc.). Each `` instance figures out its own index (`groupID`) based on its position among sibling `.form-control-group` blocks, so the typical pattern is to repeat the **whole** `` with `v-for`: ```vue
``` This produces `form.bids[0].title`, `form.bids[0].price`, `form.bids[1].title`, etc. `MultiQuantityInput` (documented below) uses a single `GroupControl` to collect a *map* of quantities (`form.tickets.adult`, `form.tickets.child`, …) instead of a repeated list — see its own example for that variant. ### Validation & error display `FormContainer` renders a default Bootstrap `Alert` listing every message in `form.errors` (replaceable via the `errors` slot), and every field adds `is-invalid` automatically when `form.errors[name]` exists. You don't need to render error text per-field unless you want to — Bootstrap will show `.invalid-feedback` siblings if you add them yourself. ### Element IDs `form.getID(field)` (available on the injected `form`) builds a unique, collision-free `id` attribute for fields, taking the surrounding `` id and any `GroupControl` into account. Components that render a real `