Introduction

Vue form elements is a set of form elements you can use in your Vue.js project. For example, you can create checkbox groups, radio button groups and sliders. All these elements support Vue's form input bindings (https://vuejs.org/v2/guide/forms.html) so you can use v-model on them. The package comes with minimal styling.

Installation

Package installation

Add the package to your project:

yarn add @acato/vue-form-elements
# or NPM:
# npm install --save @acato/vue-form-elements

Registering it to Vue.js

In your code, add the following line:

import Vue from 'vue';
import VueFormElements from '@acato/vue-form-elements';

Vue.use(VueFormElements, {
    requiredLabel: '*',
    optionalLabel: '(optional)',
});

This will add all elements from the package to your project. Alternatively you can add only the components you'll need:

import Vue from 'vue';
import VFESlider from '@acato/vue-form-elements/vue/elements/vfe-slider';

// globally
Vue.component('vfe-slider', VFESlider);

// within a component
...
    {
        props: {...},
        methods: {...},
        ...
        components: {
            'vfe-slider': VFESlider,
            ...
        }
    }
...

Add minimal styling

Some form elements such as the (non-native) select box and autocompelete, need a minimal styling to in order to be usable. Import this styling in you sass:

@import '@acato/vue-form-elements/scss/vue-form-elements';

If you don't want all the default styling, only include the styling for the elements you would like to include. There are some sass-variables available for you to easily color the elements. Please check out these variabales at @acato/vue-form-elements/scss/_variables.scss.

Basic usage

For convenience you can use the vfe-form-input-component (see below) to create a label and specific input in one. This has some advantages as it saves time and for example the label will automatically point to the correct input using the label's for-attribute. However, it's also possible to create individual inputs and labels:

vfe-label

Creates a label.

Properties:

• label String
• forInput? String
• required? Boolean

Usage:

<vfe-label label="Email" for-input="user_email"></vfe-label>

vfe-instructions

Creates an instructions text.

Properties:

• instructions String | HTML

Usage:

<vfe-instructions instructions="You can find your username in the e-mail you've received."></vfe-instructions>

vfe-input

Creates a text, number, email or password input.

Properties:

• type "text" | "number" | "email" | "password",
• name String
• id? string (defaults to input name)
• value? String | Number
• settings? VFEInputSettings (default: new VFEInputSettings())
• placeholder? String | Number
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)
• required? Boolean

Usage:

<vfe-input type="email" name="user_email" placeholder="[email protected]" v-model="user.email"></vfe-input>

vfe-textarea

Creates a textarea.

Properties:

• name String
• id? string (defaults to input name)
• value? String
• placeholder? String
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)
• required? Boolean

Usage:

<vfe-textarea name="description" placeholder="Typ your text here..." v-model="description"></vfe-textarea>

vfe-checkbox

Creates a single checkbox.

Properties:

• name String
• id? string (defaults to input name)
• value? any (default: true)
• checked? Boolean (default: false)
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

<vfe-checkbox name="newsletter" v-model="user.subscribeToNewsletter"></vfe-input>

or:

<vfe-checkbox name="terms_and_conditions" :value="{Object}" v-model="user.acceptsTermsAndConditions"></vfe-input>

vfe-radio-button

Creates a single radio button.

Properties:

• name String
• id? string (defaults to input name)
• value? any (default: true)
• checked? Boolean (default: false)
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

<vfe-radio-button name="selected_option" :value="{Object}" v-model="user.selectedOption"></vfe-radio-button>

vfe-native-select

Creates a native select (<select/>).

Properties:

• name String
• id? string (defaults to input name)
• options Array<any>
• value? any
• settings? VFESelectSettings (default: new VFESelectSettings())
• placeholder? String
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

<vfe-native-select name="favorite_color" :options="colors" :settings="settings" v-model="user.favoriteColor"></vfe-native-select>

// using an array of plain strings, resulting value will be the color name
const colors = ['red', 'blue', ...];

// using an array of objects, resulting value will be the color id
import VFESelectSettings from '@acato/vue-form-elements/vue/settings/vfe-select-settings';

const colors = [{ id: 1, name: 'red'}, { id: 2, name: 'blue'}, ... ];
const settings = new VFESelectSettings({
    label: 'name',
    value: 'id',
});

vfe-select

Creates a select that can easily be styled.

Properties:

Same as fve-native-select.

Usage:

Same as fve-native-select but instead use fve-select-tag.

vfe-checkbox-group

Creates a checkbox group.

Properties:

• name String
• id? string (defaults to input name)
• options Array<any>
• value? Array<any>
• settings? VFECheckboxGroupSettings (default: new VFECheckboxGroupSettings())
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

<vfe-checkbox-group name="cities_ive_been" :options="cities" :settings="settings" v-model="user.citiesBeen"></vfe-checkbox-group>

// using an array of plain strings, resulting value will be the color name
const cities = ['London', 'Paris', 'Berlin', ...];

// using an array of objects, resulting value will be the color id
import VFECheckboxGroupSettings from '@acato/vue-form-elements/vue/settings/vfe-checkbox-group-settings';

const cities = [{ id: 1, name: 'London'}, { id: 2, name: 'Paris'}, { id: 2, name: 'Berlin'}, ... ];
const settings = new VFECheckboxGroupSettings({
    label: 'name',
    value: 'id',
});

vfe-radio-button-group

Creates a radio button group.

Properties:

• name String
• id? string (defaults to input name)
• options Array<any>
• value? any
• settings? VFERadioButtonGroupSettings (default: new VFERadioButtonGroupSettings())
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

<vfe-radio-button-group name="favorite_city" :options="cities" :settings="settings" v-model="user.favoriteCity"></vfe-radio-button-group>

// using an array of plain strings, resulting value will be the color name
const cities = ['London', 'Paris', 'Berlin', ...];

// using an array of objects, resulting value will be the color id
import VFERadioButtonGroupSettings from '@acato/vue-form-elements/vue/settings/vfe-radio-button-group-settings';

const cities = [{ id: 1, name: 'London'}, { id: 2, name: 'Paris'}, { id: 2, name: 'Berlin'}, ... ];
const settings = new VFERadioButtonGroupSettings({
    label: 'name',
    value: 'id',
});

vfe-slider

Creates a slider or range slider.

Properties:

• type "default" | "range" (default: default)
• name String
• id? string (defaults to input name)
• value? default slider: Number | range slider: Object{min: Number, max: Number}
• settings? VFESliderSettings (default: new VFESliderSettings())
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

Default slider:

<vfe-slider name="age" :settings="settings" v-model="user.age"></vfe-slider>

import VFESliderSettings from '@acato/vue-form-elements/vue/settings/vfe-slider-settings';

const settings = new VFESliderSettings({
  min: 0,
  max: 130,
  step: 1,
});

Range slider:

<vfe-slider type="range" name="budget" :settings="settings" v-model="budget"></vfe-slider>

import VFESliderSettings from '@acato/vue-form-elements/vue/settings/vfe-slider-settings';

const settings = new VFESliderSettings({
  min: 0,
  max: 10,
  precision: 2,
  minRange: 0.5,
});

vfe-options-slider

Creates a options slider or options range slider.

Properties:

• type "default" | "range" (default: default)
• name String
• id? string (defaults to input name)
• options Array<any>
• value? default slider: any | range slider: Object{min: any, max: any}
• settings? VFEOptionsSliderSettings (default: new VFEOptionsSliderSettings())
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

Default options slider:

<vfe-options-slider name="review" :options="scores" :settings="settings" v-model="user.review"></vfe-options-slider>

import VFEOptionsSliderSettings from '@acato/vue-form-elements/vue/settings/vfe-options-slider-settings';

const scores = [
  { score: 0, label: 'Slecht' },
  { id: 5, label: 'Gemiddeld' },
  { id: 10, label: 'Goed' },
];
const settings = new VFEOptionsSliderSettings({
  value: 'score',
  orderBy: 'score',
});

Range options slider:

<vfe-options-slider type="range" name="price_range" :options="prices" :settings="settings" v-model="search.priceRange"></vfe-options-slider>

import VFEOptionsSliderSettings from '@acato/vue-form-elements/vue/settings/vfe-options-slider-settings';

const scores = [
  { maxPercentage: 25, label: '$' },
  { maxPercentage: 50, label: '$$' },
  { maxPercentage: 75, label: '$$$' },
  { maxPercentage: 100, label: '$$$$' },
];
const settings = new VFEOptionsSliderSettings({
  orderBy: 'maxPercentage',
});

vfe-autocomplete

Creates an autocomplete form input.

Properties:

• name String
• id? string (defaults to input name)
• source VFEAutocompleteSource
• value? any
• settings? VFEAutocompleteSettings (default: new VFEAutocompleteSettings())
• placeholder? String
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

<vfe-autcomplete name="hometown" :source="source" :settings="settings" v-model="user.hometown"></vfe-autcomplete>

import VFEAutocompleteSettings from '@acato/vue-form-elements/vue/settings/vfe-autocomplete-settings';
import VFEAutocompleteSource from '@acato/vue-form-elements/vue/helpets/vfe-autocomplete-source';

const citySearchRequest = (query) => { ... };
const source = new VFEAutocompleteSource(citySearchRequest, results => results.hits);
const settings = new VFEAutocompleteSettings({
    label: 'name',
    value: 'id',
    debounce: '500',
    limit: '10',
    noResultsText: 'Can\'t find city or town with that name',
});

vfe-swapbox

Creates a swapbox form input consisting of two lists of options. The first list being the currently selected options, and the second list the available options. User can swap options from one list to the other, thus selecting and deselecting options.

Properties:

• name String
• id? string (defaults to input name)
• options Array<any>
• value? Array<any>
• settings? VFESwapboxSettings (default: new VFESwapboxSettings())
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

Usage:

<vfe-swapbox name="selected_options" :options="options" :settings="settings" v-model="selectedOptions"></vfe-swapbox>

vfe-date-picker

Creates a date picker form input based on https://github.com/charliekassel/vuejs-datepicker. But works with Moment.js-objects (https://momentjs.com/) instead of vanilla Date-objects.

Properties:

• name String
• id? string (defaults to input name)
• value? Moment
• settings? VFEDatePickerSettings (default: new VFEDatePickerSettings()) *
• hasValidationError? Boolean (default: false)
• disabled? Boolean (default: false)

• Check out https://github.com/charliekassel/vuejs-datepicker for all possible settings.

Usage:

<vfe-date-picker name="start_date" :settings="settings" v-model="startDate"></vfe-date-picker>

vfe-validation-error

Creates a paragraph to show validation errors.

Properties:

• message String

Usage:

<vfe-validation-error message="Email is required"></vfe-validation-error>

vfe-form-input

Creates a label + form input of the specified type.

Properties:

• type "text" | "number" | "email" | "password" | "tel" | "url" | "date" | "time" | "datetime-local" | "month" | "week" | "textarea" | "checkbox" | "radio-button" | "native-select" | "select" | "checkbox-group" | "radio-button-group" | "slider" | "range-slider" | "options-slider" | "range-options-slider" | "autocomplete" | "swapbox" | "date-picker",
• label String
• instructions? String | HTML
• name? String (by default derived from label (snake case): "My form input" becomes 'my_form_input')
• id? String (defaults to input name)
• validationError? String
• value? any
• placeholder? String | Number
• disabled? Boolean (default: false)
• required? Boolean
• checked? Boolean
• options? Array<any>
• source? VFEAutocompleteSource
• settings? VFEInputSettings | VFESelectSettings | VFERadioButtonGroupSettings | VFECheckboxGroupSettings | VFESliderSettings | VFEOptionsSliderSettings | VFEAutocompleteSettings | VFESwapboxSettings | VFEDatePickerSettings

Usage:

<vfe-form-input type="email" label="Email" placeholder="[email protected]" label="Email is required"></vfe-form-input>

<vfe-form-input type="select" label="Favorite color" placeholder="-- select your favorite color --" :options="colors" :settings="settings"></vfe-form-input>

<vfe-form-input type="autocomplete" label="Hometown" :source="source" :settings="settings"></vfe-form-input>