# quasar-form-builder

> Form Builder. Uses Quasar Framework and Vue.

Latest version **4.0.0** (published 2026-09-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install quasar-form-builder
pnpm add quasar-form-builder
yarn add quasar-form-builder
bun add quasar-form-builder
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-09-09 |
| First published | 2021-12-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 8 |
| Unpacked size | 172.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | krasus |
| Keywords | vue, quasar, quasar-form-builder |

## Links

- npm: https://www.npmjs.com/package/quasar-form-builder
- Homepage: https://github.com/kerasus/quasar-form-builder
- npm.io page: https://npm.io/package/quasar-form-builder

## Dependencies (8)

- [vue](https://npm.io/package/vue.md) ^3.5.42
- [shvl](https://npm.io/package/shvl.md) ^3.0.2
- [quasar](https://npm.io/package/quasar.md) ^2.30.1
- [core-js](https://npm.io/package/core-js.md) ^3.50.0
- [jalali-moment](https://npm.io/package/jalali-moment.md) ^3.3.11
- [@quasar/extras](https://npm.io/package/@quasar/extras.md) ^2.0.4
- [@vee-validate/rules](https://npm.io/package/@vee-validate/rules.md) ^4.15.1
- [vue-form-builder-core](https://npm.io/package/vue-form-builder-core.md) ^1.0.3

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2026-09-09
- 3.5.6 — 2025-04-24
- 3.5.5 — 2025-04-24
- 3.5.4 — 2025-02-16
- 3.5.3 — 2025-02-16
- 3.5.2 — 2025-01-25
- 2.5.7 — 2025-01-25
- 3.5.1 — 2024-12-21
- 3.5.0 — 2024-11-05
- 3.4.0 — 2024-11-05
- 3.3.0 — 2024-10-30
- 3.2.2 — 2024-09-09
- 3.2.1 — 2024-09-09
- 3.2.0 — 2024-08-31
- 3.1.5 — 2024-08-21
- … 159 more at https://npm.io/package/quasar-form-builder/versions

## README

# quasar-form-builder

This package just get you props and then give you form with inputs (it's created with **FormBuilder** component) or just any input you need.

## install

```
npm i quasar-form-builder
```

## Usage

To use it in vue files, you need to import the component you want and use it like a regular component, for example:

```vue
<template>
  <form-builder v-model:inputs="inputs"
                v-model:formData="formData"
                :readonly="readonly"
                :disable="disable"
                :loading="loading"
                @inputClick="onClick"
                @keydown="onKeyPress" />
</template>

<script setup lang="ts">
import { type FormInputItem } from 'quasar-form-builder'
import { FormBuilder } from 'quasar-form-builder';

const inputs = ref<FormInputItem[]>([])
const formData = ref<Record<string, any>>({})

const readonly = ref(false)
const disable = ref(false)
const loading = ref(false)

const onClick = (data: any) => {
  console.log('data clicked:', data)
}

const onKeyPress = (data: any) => {
  console.log('key press:', data)
}
</script>
```

<!-- Generator removed: see dev/App.vue playground example -->

## Features:

### Outside label (`outsideLabel`) prop

A new optional prop `outsideLabel` (type: String) is supported by many form input components. When provided, the component renders an external label element above the input using the CSS class `outside-label`. Example in a component template:

```vue
<div v-if="outsideLabel" class="outside-label">{{ outsideLabel }}</div>
```

This prop is useful when you want to show a label outside (above) the input instead of using the component's internal `label` or `stackLabel` behavior.

Currently supported components (in `src/components`):

- FormBuilderInput
- FormBuilderInputEditor
- FormBuilderSelect
- FormBuilderCheckbox
- FormBuilderColor
- FormBuilderDate
- FormBuilderDateTime
- FormBuilderTime
- FormBuilderSlider
- FormBuilderRangeSlider
- FormBuilderOptionGroup
- FormBuilderFile
- FormBuilderTiptapEditor
- FormBuilderToggleButton
- FormBuilderButton

Usage example (inside FormBuilder JSON or component props):

```json
{
  "type": "Input",
  "outsideLabel": "External label text",
  "label": "Field label (optional)"
}
```

Styling: the class used is `outside-label`. You can override or extend it in your styles (the components include a simple default margin and font-size).


- ### FormBuilder

| props   | default | type    |
| ------- | :-----: | :------ |
| value   |   [ ]   | Array   |
| disable |  false  | Boolean |

> #### important !
>
> For any input you want,you have to specify its type.

```vue
<template>
  <form-builder v-model:value="inputs" />
</template>

<script>
import { FormBuilder } from 'quasar-form-builder';
export default {
  components: { FormBuilder },
  data() {
    return {
      inputs: [
        {
          type: 'Input', // Avatar, date, dateTime and etc.
          label: 'Label',
          //and other props of FormBuilderInput component
        },
        {
          type: 'date',
          label: 'Label' /*and other props of FormBuilderDateTime component*/,
        },
        {
          type: 'Slider',
          label: 'Label' /*and other props of FormBuilderSlider component*/,
        },
      ],
    };
  },
};
</script>
```

- ### FormBuilderAvatar
  - types
    - Avtar

| props     | default | type   |
| --------- | :-----: | :----- |
| size      |  50px   | String |
| fontSize  |  14px   | String |
| color     | primary | String |
| textColor |  white  | String |

- ### FormBuilderCheckbox
  - types
    - Checkbox

| props      | default | type                                   |
| ---------- | :-----: | :------------------------------------- |
| value      |   ' '   | Object, String, Array, Number, Boolean |
| label      |   ' '   | String                                 |
| color      | primary | String                                 |
| disable    |  false  | Boolean                                |
| trueValue  |  true   | Object, String, Array, Number, Boolean |
| falseValue |  false  | Object, String, Array, Number, Boolean |

- ### FormBuilderDateTime

  - types

    - date

      | props    | default | type          |
      | -------- | :-----: | :------------ |
      | value    |   ' '   | Object, Array |
      | calendar | persian | String        |
      | multiple |  false  | Boolean       |
      | disable  |  false  | Boolean       |

    - time

      | props   | default | type          |
      | ------- | :-----: | :------------ |
      | value   |   ' '   | Object, Array |
      | disable |  false  | Boolean       |

    - dateTime

      | props    | default | type          |
      | -------- | :-----: | :------------ |
      | value    |   ' '   | Object, Array |
      | calendar | persian | String        |
      | multiple |  false  | Boolean       |
      | disable  |  false  | Boolean       |

    - dateRange

      | props    | default | type          |
      | -------- | :-----: | :------------ |
      | value    |   ' '   | Object, Array |
      | calendar | persian | String        |
      | multiple |  false  | Boolean       |
      | disable  |  false  | Boolean       |
      | range    |  true   | Boolean       |

    - dateMultipleRange

      | props    | default | type          |
      | -------- | :-----: | :------------ |
      | value    |   ' '   | Object, Array |
      | calendar | persian | String        |
      | multiple |  true   | Boolean       |
      | disable  |  false  | Boolean       |
      | range    |  true   | Boolean       |

- ### FormBuilderFile
  - types
    - File

| props     | default | type                                   |
| --------- | :-----: | :------------------------------------- |
| value     |   ' '   | Object, String, Array, Number, Boolean |
| label     |   ' '   | String                                 |
| disable   |  false  | Boolean                                |
| clearable |  true   | Boolean                                |
| src       |   ' '   | String, Number, Boolean, Array         |

- ### FormBuilderInput
  - types
    - Input

| props   | default | type                    |
| ------- | :-----: | :---------------------- |
| value   |   ' '   | String, Number, Boolean |
| label   |   ' '   | String                  |
| disable |  false  | Boolean                 |

- ### FormBuilderInputEditor
  - types
    - InputEditor

| props   | default | type                    |
| ------- | :-----: | :---------------------- |
| value   |   ' '   | String, Number, Boolean |
| label   |   ' '   | String                  |
| disable |  false  | Boolean                 |

- ### FormBuilderOptionGroup
  - types
    - date
    - OptionGroup
    - optionGroupRadio
    - optionGroupCheckbox
    - optionGroupToggle

| props   | default | type                                   |
| ------- | :-----: | :------------------------------------- |
| value   |   ' '   | Object, String, Array, Number, Boolean |
| options |   []    | Array                                  |

- ### FormBuilderSlider
  - types
    - Slider

| props   | default | type    |
| ------- | :-----: | :------ |
| value   |    0    | Number  |
| min     |    0    | Number  |
| max     |   100   | Number  |
| disable |  false  | Boolean |

- ### FormBuilderRangeSlider
  - types
    - RangeSlider

| props   |       default       | type    |
| ------- | :-----------------: | :------ |
| value   | { min: 9, max: 35 } | Object  |
| label   |         ' '         | String  |
| disable |        false        | Boolean |
| range   |        true         | Boolean |

- ### FormBuilderSelect
  - types
    - Select

| props         | default | type                           |
| ------------- | :-----: | :----------------------------- |
| value         |   []    | Array, String, Number, Boolean |
| options       |   []    | Array                          |
| optionDisable | disable | String                         |
| optionValue   |  value  | String                         |
| optionLabel   |  label  | String                         |
| label         |   ' '   | String                         |
| disable       |  false  | Boolean                        |
| multiple      |  false  | Boolean                        |
| useChips      |  false  | Boolean                        |

#### example of options prop usage :

```vue
<template>
  <form-builder v-model:value="inputs" />
</template>

<script>
import { FormBuilder } from 'quasar-form-builder';
export default {
  components: { FormBuilder },
  data() {
    return {
      inputs: [
        {
          type: 'Select', // Avatar, date, dateTime and etc.
          label: 'Label',
          options: [
            { label: 'some label', value: 'some value' }, //for first option of select input
            { label: 'some label', value: 'some value' }, //for second option of select input
            { label: 'some label', value: 'some value' }, //for third option of select input
          ],
          optionLabel: 'label',
          optionValue: 'value',
          //and other props of FormBuilderSelect component
        },
      ],
    };
  },
};
</script>

## Playground / Example (from dev/App.vue)

The repository includes a development playground at `dev/App.vue` which demonstrates how to wire up and interact with `FormBuilder`. Below are the common integration points shown in the playground.

- Provide the inputs schema via `v-model:inputs` (an array describing each field).
- Bind current values via `v-model:formData` (an object populated as the user interacts).
- Control global states using `:readonly`, `:disable`, and `:loading` props on the `FormBuilder` component.
- Use a template `ref` (`ref="formBuilderRef"`) to call helper methods exposed by the FormBuilder instance:
  - `getNormalizedFormData(inputs)` — returns a normalized/flattened form data object based on the inputs schema.
  - `clearValues()` — clear/reset form values programmatically.
- Listen to `@inputClick` and `@keydown` events to react to input interactions.
- Register custom components as input types by passing a `shallowRef` to the `type` field of an input item.

Simplified example inspired by `dev/App.vue`:

```vue
<template>
  <form-builder
    ref="formBuilderRef"
    v-model:inputs="inputs"
    v-model:formData="formData"
    :readonly="readonly"
    :disable="disable"
    :loading="loading"
    @inputClick="onClick"
    @keydown="onKeyPress" />
</template>

<script setup>
import { ref, shallowRef } from 'vue'
import FormBuilder from './src/FormBuilder.vue'
import CustomComponent from './dev/components/CustomComponent.vue'

const formBuilderRef = ref(null)
const CustomComponentInput = shallowRef(CustomComponent)

const inputs = ref([
  { type: 'file', label: 'just capture', multiple: true, clearable: true },
  { type: 'select', name: 'question_type', options: [ { label: 'konkur', value: 'konkur' } ] },
  { type: 'submit', label: 'submit btn' },
  { type: CustomComponentInput, props: { name: 'ali' }, name: 'ali', label: 'شناسه علی' },
  { type: 'date', name: 'last_modification_time', label: 'required date with label' }
])

const formData = ref({})

const getData = () => {
  console.log('Form Data Object: ', formData.value)
  if (formBuilderRef.value) {
    console.log('Normalized Form Data:', formBuilderRef.value.getNormalizedFormData(inputs.value))
  }
}

const clearInputValues = () => {
  if (formBuilderRef.value) formBuilderRef.value.clearValues()
}
</script>
```


The dev playground also shows several utility controls (buttons) such as: get data, clear inputs, toggle `loading`, toggle `readonly`/`disable`, and change screen `dir` between `ltr` and `rtl`.

## API / Instance Methods

When you hold a `ref` to the `FormBuilder` component instance (for example `ref="formBuilderRef"`), the playground demonstrates calling these helpers:

- `getNormalizedFormData(inputs)` — returns a normalized form data object based on the provided `inputs` schema.
- `clearValues()` — clears or resets all input values managed by the `FormBuilder` instance.

Example usage:

```js
if (formBuilderRef.value) {
  formBuilderRef.value.clearValues()
  const normalized = formBuilderRef.value.getNormalizedFormData(inputs.value)
}
```

## Events

The `FormBuilder` emits a few useful events demonstrated in the playground:

- `@inputClick` — emitted when an input is clicked.
- `@keydown` — emitted for keyboard interactions inside inputs.

Bind handlers directly on the component like:

```vue
<form-builder @inputClick="onClick" @keydown="onKeyPress" />
```

## Notes from the playground

- Use `v-model:inputs` to supply the inputs schema array.
- Use `v-model:formData` to two-way bind form values.
- Control global presentation/interaction via `:readonly`, `:disable`, and `:loading` props.
- Provide custom input components by assigning a `shallowRef` to the `type` field of an input (see the playground `CustomComponentInput`).

---
_Source: https://npm.io/package/quasar-form-builder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._