Configuration
Options
Options can be passed to vjsf using the options prop or can be defined more locally on a specific property using the "x-options" annotation. Children properties will inherit from the options defined in their parents.
| Key | Default | Description |
|---|---|---|
| locale | "" | The default value is read in "$vuetify.lang.current". See the Messages section |
| defaultLocale | "" | The default value is read in "$vuetify.lang.defaultLocale". |
| rootDisplay | "" | equivalent of x-display annotation on the root object of the schema, can be "tabs" or "expansion-panels" |
| objectContainerClass | "" | |
| sectionsClass | "pl-2 pt-2" | |
| sectionsTitlesClasses | [ "title", "subtitle-1", "subtitle-2" ] | |
| arrayItemsTitlesClasses | [ "title", "subtitle-1", "subtitle-2" ] | |
| childrenClass | "" | |
| fieldProps | {} | props passed to the underlying components for simple fields (v-text-field, v-select, etc.) |
| fieldColProps | { "cols": 12 } | props passed to the v-col component that wraps any field. Use "cols", "xs", "md", etc. to customize your form layout. |
| readOnlyFieldProps | { "hideDetails": true } | |
| textFieldProps | {} | props passed to the underlying v-text-field components |
| textareaProps | { "filled": true } | props passed to the underlying v-textarea components |
| numberProps | {} | props passed to the underlying v-text-field components with type="number" |
| sliderProps | {} | props passed to the underlying v-slider components |
| checkboxProps | {} | props passed to the underlying v-checkbox components |
| switchProps | {} | props passed to the underlying v-switch components |
| comboboxProps | {} | props passed to the underlying v-combobox components |
| selectProps | {} | props passed to the underlying components for select fields |
| fileInputProps | {} | props passed to the underlying v-file-input components |
| radioGroupProps | {} | props passed to the underlying v-radio-group components |
| radioItemProps | {} | props passed to the underlying v-radio-item components |
| tabsProps | { "grow": true } | props passed to the underlying v-tabs component when relevant |
| expansionPanelsProps | { "mandatory": true } | props passed to the underlying v-expansion-panels component when relevant |
| dialogProps | { "maxWidth": 500 } | props passed to the underlying v-dialog component when relevant |
| dialogCardProps | {} | props passed to the v-card component inside a v-dialog component when relevant |
| colorPickerProps | {} | props passed to the underlying v-color-picker component when relevant |
| timePickerProps | {} | props passed to the underlying v-time-picker component when relevant |
| datePickerProps | { "scrollable": true } | props passed to the underlying v-date-picker component when relevant |
| arrayItemCardProps | {} | props passed to the underlying v-card component of each item of an editable array |
| arrayItemColProps | { "cols": 12 } | props passed to the underlying v-col component of each item of an editable array |
| stepperProps | {} | |
| verticalStepperProps | {} | |
| tooltipProps | { "left": true, "openOnHover": false, "openOnClick": true } | |
| removeAdditionalProperties | true | force the removal of properties found in the model but not defined in the schema |
| disableAll | false | force disabling all fields ignoring the readOnly attributes |
| hideReadOnly | false | by default read-only properties are rendered as disabled fields, set this to true to hide them entirely |
| hideReadOnlyLabels | false | |
| hideReadOnlyEmpty | false | |
| hideReadOnlyTooltips | false | |
| deleteReadOnly | false | set this to true to not only hide read-only properties, but also remove them from the model |
| hideInArrayItem | false | |
| filesAsDataUrl | false | |
| hideTooltips | false | by default descriptions are rendered as help tooltip on properties, set this to true to disable this functionality |
| disableSorting | false | by default editable array are sortable, set this to true to disable this functionality |
| sortableOptions | {} | |
| context | {} | an optional contextual information object, properties from here can be used as variables in URL templates |
| rules | {} | some custom rule functions that can be referenced by the x-rules annotation on properties |
| initialValidation | "defined" | configure display of properties validation errors at initial rendering of the form ("all" to show validation errors of all properties, "defined" to show validation errors of the properties with pre-existing content, "none" to wait for user interactions of explicit call of the validate method) |
| idPrefix | "" | a prefix applied to generated ids if you want to prevent potential conflicts |
| markdownit | {} | options given to markdownit if you leave the markdown option to its default value |
| editMode | "dialog" | change the way editable arrays are rendered. Use "dialog" to edit items in separate dialogs, use "inline" to edit items in place. |
| arrayOperations | [ "create", "update", "duplicate", "copy", "paste", "delete" ] | |
| autofocus | false | attempt to give focus to the first simple field rendered. |
| httpOptions | {} | |
| selectAll | false | |
| autoFixArrayItems | true | modify the items of arrays existing in the model (set default values, set const values, remove additional properties), you can try disabling this if you run into performance issues |
| useValidator | false | See the JSON schema validator section. Activate using the validator to display validation errors as a complement to the validation rules managed by vjsf directly. |
| evalMethod | "propertyExpr" | See the Expressions section. For security reasons this option can only be changed in the main options object given to vjsf, not in x-options annotations inside the schema. |
| easyMDEOptions | {} | See EasyMDE documentation |
| maxLengthCounter | true | |
| markdown | window.markdownit().render if markdownit is available, identity function otherwise | a function that takes a markdown text and returns HTML, used for descriptions and slots |
| httpLib | this.axios or this.$http or this.$axios or window.axios | a simple HTTP client used to fetch select options from HTTP requests |
Messages
You can define a special "messages" option to overwrite the default localized messages.
| Message key | Default |
|---|---|
| required | This information is required |
| noData | No matching value found |
| search | Search... |
| minimum | The value must be greater than or equal to {minimum} |
| exclusiveMinimum | The value must be greater than {exclusiveMinimum} |
| maximum | The value must be lower than or equal to {maximum} |
| exclusiveMaximum | The value must be lower than {exclusiveMaximum} |
| minLength | {minLength} characters minimum |
| maxLength | {maxLength} characters maximum |
| minItems | No less than {minItems} items |
| maxItems | No more than {maxItems} items |
| pattern | The expected pattern is not satisfied |
| mdeLink1 | [Link title |
| mdeLink2 | ](link url) |
| mdeImg1 |  |
| mdeTable1 | |
| mdeTable2 | | Column 1 | Column 2 | ColoColumnnne 3 | | -------- | -------- | -------- | | Text | Text | Text | |
| bold | Bold |
| italic | Italic |
| heading | Title |
| quote | Quote |
| unorderedList | Unordered list |
| orderedList | Ordered list |
| createLink | Create a link |
| insertImage | Insert an image |
| createTable | Create a table |
| preview | Aperçu du rendu |
| mdeGuide | Documentation de la syntaxe |
| undo | Undo |
| redo | Redo |
| selectAll | Select all |
| stepperContinue | continue |
| openMenu | open menu |
| delete | delete |
| duplicate | duplicate |
| copy | copy |
| paste | paste |
Icons
You can define a special "icons" option to overwrite the default icons. Default icons are initialized based on current iconfont configured on your Vuetify instance.
| Icon key | Default |
|---|---|
| calendar | mdi-calendar |
| clock | mdi-clock |
| info | mdi-information |
| add | mdi-plus |
| edit | mdi-pencil |
| delete | mdi-delete |
| arrayMenu | mdi-dots-vertical |
| duplicate | mdi-plus-circle-multiple-outline |
| copy | mdi-content-copy |
| paste | mdi-content-paste |
Formatting functions
You can define a special "formats" option to overwrite the default formatting functions that are used to display some field values.
| Message key | Default |
|---|---|
| time | (time, locale) => { const date = new Date(`${new Date().toISOString().split('T')[0]}T${time}`); return new Date(date.getTime() + date.getTimezoneOffset() * 60000).toLocaleTimeString(locale); } |
| date | (dateStr, locale) => { const date = new Date(dateStr); return new Date(date.getTime() + date.getTimezoneOffset() * 60000).toLocaleDateString(locale); } |
| date-time | (dateTime, locale) => { return new Date(dateTime).toLocaleString(locale); } |
Annotations
Annotation is the name we give to special attributes defined on properties in your schema. These attributes are prefixed by "x-" to signify that they are not part of the standard JSON schema syntax. They should be ignored by validators and other tools.
Disclaimer: the following list contains only very brief explanations. The real documentation is in the examples.
| Annotation key | Usage |
|---|---|
| x-options | Overwrite some of the options for this property and its children. |
| x-display | Used to switch the rendering mode of a property. We try to use as little of these as possible and rely on indications from the standard JSON schema syntax itself to render the form, but sometimes some ambiguity has to be resolved this way. For example this is used to force rendering sections as tabs or expansion panels. |
| x-fromUrl / x-fromData | Used to populate selects from the results of HTTP requests or some other part of the model. See the Expressions section for possibilities of x-fromData. |
| x-itemKey / x-itemTitle / x-itemIcon | Used to configure rendering of options in selects. |
| x-props | An object of props to pass directly to the underlying Vuetify component. |
| x-cols | The width of the v-col component wrapping the property (default is 12). You can use the fieldColProps option for further layout customization. |
| x-slots | An object of textual contents to be displayed before and after the property or to be passed as slots to the underlying vuetify component. |
| x-rules | Some custom rule functions for validating this property. |
| x-rules | Some custom rule functions for validating this property. |
Expressions
Some functionalities require expressions given in the JSON schema and evaluated using contextual data. For example the x-if and fromData annotations use these expressions. The method used to evaluate the expressions can be changed with the evalMethod option, possible values are:
You can debug expressions by setting localStorage.debug = 'vjsf:expr'.
| Value of evalMethod | Explanation |
|---|---|
| propertyExpr (default) | Based on the property-expr module. Expressions are simple deep getters into the contextual data. |
| evalExpr | Based on the eval-expr module. Only logical expressions are allowed. |
| newFunction |
Based on dynamically created JS functions. Expressions are complete JS expressions.
WARNING ! This method implies that you trust the source of the JSON schema as much as you trust your own source code. |
Call for help: if someone knows of a better solution for this problem, for example a library with rich expression evaluation but without the security liability of using new Function, please submit a ticket or a pull request !
The expressions are given some contextual data as input, here are its members:
| Data | Explanation |
|---|---|
| root | The main complete model being handled by vjsf. |
| model | The model being handled by vjsf at this level in the schema definition. |
| context | The options.context object. |
| parent.value | The parent object in the model. |
| parent.schema | The parent property schema. |
| parent.parent.value | The grand-parent object in the model. Etc. |
JSON schema validator
Some functionalities require that you provide a JSON schema validator. This is the case for the if/then/else syntax and for the useValidator option. You can provide the validator using different methods:
- If you load third-party.js Ajv will be used along with ajv-formats and ajv-i18n.
- You can provide Ajv, ajvAddFormats and ajvLocalize as global variables or as options and an ajv instance will be created.
- You can provide an ajv instance in the ajv option.
- You can provide a validator function as an option. This function must accept a schema and return a function that will take a model and return either null (no error) or an error message as a string.