MatrixElement
Renders a matrix of input fields.
Basic Usage
<MatrixElement>
component can be used in a <Vueform>
component:
<template>
<!-- Default view -->
<Vueform>
<MatrixElement
name="matrix"
/>
</Vueform>
</template>
<template>
<!-- Table view -->
<Vueform>
<MatrixElement
name="matrix"
:presets="['matrix-table']"
/>
</Vueform>
</template>
Configuration options can be passed over as regular component props. Check out Options section for available configuration options.
Options
Find below the list of options that can use to configure MatrixElement
component. Options can be passed to the component via props in inline templates, or in the element's object when using schema
.
inputType
- Type:
string|object
- Default:
radio
<MatrixElement input-type="text" ... />
<MatrixElement :input-type="{ type: 'select', items: [1,2,3,4,5] }" ... />
The default type of the matrix fields can be defined in two ways:
- As a
string
representing thetype
property of an element, such astext
,textarea
,slider
, etc. - As an
object
containing the configuration options of an element, withtype
as a required property. For example:{ type: 'select', items: [1,2,3,4,5] }
.
When the inputType
is set to radio
(which is the default), the matrix data is structured as an object
where each key represents a row value, and each value corresponds to a column value:
<MatrixElement input-type="radio" ... />
For inputType
values of checkbox
or toggle
, the matrix data is an object
in which each key represents a row value, and each value is an array
containing the relevant column values:
<MatrixElement input-type="checkbox" ... />
For all other inputType
settings, the matrix data is an object
where each key represents a row, and each value is an object with keys for each column and corresponding column values.
<MatrixElement input-type="text" ... />
items
- Type:
array|object|string|function
- Default:
[]
<MatrixElement input-type="select" :items="[1,2,3,4,5]" ... />
If the inputType
is set to select
, multiselect
, tags
, checkboxgroup
, or radiogroup
, you can use this option to specify the items
property for the element. This provides an alternative to defining inputType
as an object with an items
property.
cols
- Type:
array|object
- Default:
[]
Defines the columns of the matrix.
Columns can be specified as follows:
- As an
array
ofstring
values. In this setup, all columns will share the same label and value, and the element type will default to theinputType
:
<MatrixElement :cols="['Column 1', 'Column 2']" ... />
- As an
object
, where each key becomes the column value at the data level, and each value is the column label. The element type will still be the defaultinputType
:
<MatrixElement :cols="{
column_1: 'Column 1',
column_2: 'Column 2',
}" ... />
- As an
array
ofobject
s withlabel
andvalue
properties. Here,label
specifies the displayed column label, whilevalue
represents the column's data value. The element type will also be the defaultinputType
:
<MatrixElement :cols="[
{ value: 'column_1', label: 'Column 1' },
{ value: 'column_2', label: 'Column 2' },
]" ... />
If an array
of object
s is used for columns, additional properties can be set for each column individually, including: inputType
, minWidth
, maxWidth
, and padding
.
<MatrixElement :cols="[
{
value: 'name',
label: 'Name',
inputType: { type: 'text', placeholder: 'Type here', rules: 'required' },
minWidth: 240,
},
{
value: 'age',
label: 'Age',
inputType: { type: 'slider', min: 1, max: 99, rules: 'numeric|min:18' },
maxWidth: 100,
},
]" ... />
Column Conditions
When using an array
of object
s for cols
, a conditions
property can also be added. This allows conditions to be applied to each column individually, similar to any other element. Learn more about using conditions.
<CheckboxElement name="show_second" text="Show Column 2" />
<MatrixElement inputType="text" :cols="[
{ value: 'column_1', label: 'Column 1' },
{ value: 'column_2', label: 'Column 2', conditions: [
['show_second', true]
] },
]" ... />
colWrap
- Type:
boolean
- Default:
true
<MatrixElement :col-wrap="true" ... />
<MatrixElement :col-wrap="false" ... />
Determines whether column headers can wrap onto multiple lines. If columns require more space than is available, they will overflow the container with a scroll option.
hideCols
- Type:
boolean
- Default:
false
<MatrixElement hide-cols ... />
Whether column headers should be hidden.
stickyCols
- Type:
boolean
- Default:
false
<MatrixElement :add-class="{ grid: 'max-h-[174px]' }" sticky-cols ... />
Whether column headers should be sticky if the rows are scrollable.
rows
- Type:
array|object|number
- Default:
1
Defines the rows of the matrix.
Rows can be defined in several ways:
- As an
array
ofstring
values. In this case, all rows will have the same label and value:
<MatrixElement :rows="['Row 1', 'Row 2']" ... />
- As an
object
, where each key represents the row's data value, and each value becomes the row label:
<MatrixElement :rows="{
row_1: 'Row 1',
row_2: 'Row 2',
}" ... />
- As an
array
ofobject
s withlabel
andvalue
properties. Here,label
specifies the row’s display label, whilevalue
represents the row’s data value:
<MatrixElement :rows="[
{ value: 'row_1', label: 'Row 1' },
{ value: 'row_2', label: 'Row 2' },
]" ... />
- As a
number
(>=0
), allowing dynamic rows. This setup enables users to freely add or remove rows without predefined labels. In this case, you can use options such asmin
,max
,canAdd
,canRemove
, andaddText
.
<MatrixElement :rows="2" ... />
Row Conditions
When defining rows
as an array
of object
s, a conditions
property can be added to each row. This works the same way as conditions for any other element. Learn more about conditions.
<CheckboxElement name="show_second" text="Show Row 2" />
<MatrixElement inputType="text" :rows="[
{ value: 'row_1', label: 'Row 1' },
{ value: 'row_2', label: 'Row 2', conditions: [
['show_second', true]
] },
]" ... />
rowWrap
- Type:
boolean
- Default:
true
<MatrixElement :row-wrap="true" ... />
<MatrixElement :row-wrap="false" ... />
Whether row labels are allowed to break into multiple lines.
hideRows
- Type:
boolean
- Default:
false
<MatrixElement hide-rows ... />
Whether row labels should be hidden.
stickyRows
- Type:
boolean
- Default:
false
<MatrixElement sticky-rows ... />
Whether row labels should be sticky if the columns are scrollable.
min
- Type:
number|string
- Default:
-1
<MatrixElement :rows="2" :min="2" ... />
Specifies the minimum number of rows that must remain when using dynamic rows. When set, the user cannot remove rows below this limit.
max
- Type:
number|string
- Default:
-1
<MatrixElement :rows="2" :max="2" ... />
Defines the maximum number of rows allowed when using dynamic rows. Users cannot add rows beyond this limit.
canAdd
- Type:
boolean
- Default:
true
<MatrixElement :rows="2" :can-add="false" ... />
Whether new rows can be added to the matrix when using dynamic rows.
canRemove
- Type:
boolean
- Default:
true
<MatrixElement :rows="2" :can-remove="false" ... />
Whether rows can be removed when using dynamic rows.
addText
- Type:
string
- Default:
locale.elements.list.add
<MatrixElement :rows="2" add-text="Add row" ... />
The label of the add button when using dynamic rows. Defaults to elements.list.add
from the current locale.
minWidth
- Type:
number|string
- Default:
min-content
<MatrixElement :min-width="240" ... />
The minimum width of columns except for the row label column (if present). If it is a number it will resolve to px
. The value becomes the first param of minmax
in grid-template-columns
property.
maxWidth
- Type:
number|string
- Default:
1fr
<MatrixElement :max-width="100" ... />
The maximum width of columns except for the row label column (if present). If it is a number it will resolve to px
. The value becomes the second param of minmax
in grid-template-columns
property.
gap
- Type:
string|number
- Default:
16
<MatrixElement :gap="0" ... />
<MatrixElement gap="2rem" ... />
The gap between matrix cells. If the value is a number
it resolves to px
.
padding
- Type:
boolean
- Default:
false
<MatrixElement :padding="false" input-type="text" ... />
<MatrixElement :padding="true" input-type="text" ... />
Whether an extra horizontal padding should be added field wrappers.
scrollable
- Type:
boolean
- Default:
true
<MatrixElement :scrollable="false" ... />
Whether the matrix should be horizontally scrollable when columns overflow the container.
templateColumns
- Type:
string|function
- Default:
null
<MatrixElement template-columns="2fr 1fr 1fr" ... />
Manually overrides the grid-template-columns
style property of the grid.
name
- Type:
string|number
- Default:
undefined
- Required:
true
<MatrixElement name="element" ... />
The name of the matrix element and the prefix of child elements.
id
- Type:
string
- Default:
null
<MatrixElement id="field-id" ... />
The the id
of the matrix element.
readonly
- Type:
boolean|function|array|object
- Default:
false
<MatrixElement readonly input-type="text" ... />
Makes the child elements readonly.
disabled
- Type:
boolean|function|array|object
- Default:
false
<MatrixElement :disabled="true" ... />
<MatrixElement :disabled="prop" ... /> <!-- computed / data (ref) prop -->
<MatrixElement :disabled="[['text', 'value']]" ... /> <!-- conditional -->
<MatrixElement :disabled="(el$, form$) => { return /* boolean */ }" ... />
Disables the matrix.
If can be a boolean
value.
It can be a computed / data (ref) prop.
It can be an array
of conditions. When all conditions are met the element will become disabled.
It can be a function that receives the el$
element instance and form$
form instance params and expected to return a boolean
.
label
- Type:
string|object|function
- Default:
null
- Localizable:
true
Sets a label for the element. Can be defined as a string
, a Vue component
object with a render function or as a function
that receives el$
as its first a param.
Can also be defined via
#label
slot.
info
- Type:
string|object
- Default:
null
- Localizable:
true
<MatrixElement label="Info" info="Info" ... />
Renders an ElementInfo
component next to the element's label. By default the icon shows the value of info
when hovered, which can contain plain text or HTML. The element needs to have a label
defined in order for info to be rendered.
Can be also defined via
#info
slot.
infoPosition
- Type:
string
- Default:
right
<MatrixElement label="Top" info="Top" info-position="top" ... />
<MatrixElement label="Right" info="Right" info-position="right" ... />
<MatrixElement label="Left" info="Left" info-position="left" ... />
<MatrixElement label="Bottom" info="Bottom" info-position="bottom" ... />
Sets the position of the info
tooltip.
Can be also defined via
#info
slot.
description
- Type:
string|object
- Default:
null
- Localizable:
true
<MatrixElement description="Lorem ipsum dolor sit amet" ... />
Renders the contents of description
prop in the ElementDescription
component below the matrix. It can contain plain text or HTML.
Can be also defined via
#description
slot.
before
- Type:
object|string|number
- Default:
null
- Localizable:
true
<MatrixElement before="Before" ... />
Renders the contents of before
in a ElementText
component before the matrix. It can contain plain text or HTML.
Can be also defined via
#before
slot.
between
- Type:
object|string|number
- Default:
null
- Localizable:
true
<MatrixElement description="Description" between="Between" ... />
Renders the contents of between
in a ElementText
component between the matrix and the description. It can contain plain text or HTML.
Can be also defined via
#between
slot.
after
- Type:
object|string|number
- Default:
null
- Localizable:
true
<MatrixElement description="Description" rules="required" after="After" ... />
Renders the contents of after
in a ElementText
component after the description and error. It can contain plain text or HTML.
Can be also defined via
#after
slot.
default
- Type:
object
- Default:
{}
Set the default value of the matrix.
If the inputType
is radio
(the default setting), default
is an object
where each key represents a row value, and each value corresponds to a column value.
<MatrixElement
inputType="radio"
:default="{
row_1: 'column_1',
row_2: 'column_2'
}"
:rows="{
value: 'row_1',
label: 'Row 1'
},
{
value: 'row_2',
label: 'Row 2'
}"
:cols="{
value: 'column_1',
label: 'Column 1'
},
{
value: 'column_2',
label: 'Column 2'
}""
... />
If inputType
is checkbox
or toggle
, default
is an object
where each key represents a row value, and each value is an array
containing the relevant column values.
<MatrixElement
inputType="checkbox"
:default="{
row_1: ['column_1'],
row_2: ['column_1', 'column_2']
}"
:rows="{
value: 'row_1',
label: 'Row 1'
},
{
value: 'row_2',
label: 'Row 2'
}"
:cols="{
value: 'column_1',
label: 'Column 1'
},
{
value: 'column_2',
label: 'Column 2'
}""
... />
For any other inputType
, default
is an object
where each key represents a row value, and each value is an object with keys for each column and corresponding column values.
<MatrixElement
inputType="text"
:default="{
row_1: {
column_1: 'a',
column_2: 'b'
},
row_2: {
column_1: 'c',
column_2: 'd'
},
}"
:rows="{
value: 'row_1',
label: 'Row 1'
},
{
value: 'row_2',
label: 'Row 2'
}"
:cols="{
value: 'column_1',
label: 'Column 1'
},
{
value: 'column_2',
label: 'Column 2'
}"
... />
formatData
- Type:
function
- Default:
null
<MatrixElement :format-data="(n, v) => ({[n]: /* transformed value */ })" ... />
Formats the element's requestData
.
The first param is the element's name
, the second is the value
. The return value should be an object
, which only contains one item with the element's name
as key and the transformed value
as value.
formatLoad
- Type:
function
- Default:
null
<MatrixElement :format-load="(v) => /* transformed value */" ... />
Formats the data being loaded to the element when using load(data, format: true)
. It receives the value being loaded to the element as its first param and should return the formatted value of the element.
submit
- Type:
boolean
- Default:
true
<MatrixElement :submit="false" ... />
If set to false
the element's data will not be included in requestData
and will not be submitted.
rules
- Type:
array|string|object
- Default:
null
<MatrixElement rules="required" ... />
Defines the validation rules for the element.
Currently, the only official validation rule available for a matrix is required
. When this rule is applied, all fields within the matrix must contain a non-null value.
If the entire matrix requires validation, avoid setting the
required
rule on individual fields throughinputType.rules
. Instead, apply therequired
rule to the matrix element itself to achieve better performance.
fieldName
- Type:
string
- Default:
name|label
<MatrixElement field-name="Field name" rules="required" ... />
Sets the name of the field in validation rule messages.
messages
- Type:
object
- Default:
{}
<MatrixElement rules="required" :messages="{ required: 'Please fill in all fields' }" ... />
Overrides the default messages for the element's validation rules. The value is an object
where each key is the name of a validation rule and the value is the error message that will be displayed when the rule fails.
You can override validation messages on form level with
messages
.
displayErrors
- Type:
boolean
- Default:
true
<MatrixElement :display-errors="false" ... />
Whether element errors should be displayed.
conditions
- Type:
array
- Default:
[]
<!-- field1 - type 'show' -->
<TextElement name="field1" ... />
<!-- field2 - only if field1 == 'show' -->
<MatrixElement name="field2" :conditions="[['field1', 'show']]" ... />
<!-- field3 - only if field1 != 'show' -->
<MatrixElement name="field3" :conditions="[['field1', '!=', 'show']]" ... />
<!-- field4 - only if field1 == 'show' -->
<MatrixElement name="field4" :conditions="[
(form$, el$) => form$.el$('field1')?.value === 'show'
]" ... />
Shows or hides an element based on the provided conditions.
If an element's conditions are unmet the element will be hidden and its available
property will become false
. If hidden, its value will not be part of requestData
.
Conditions can be provided as an array
, where each item has to be either an array
or a function
. The element will only become available
if all the conditions are fulfilled.
If a condition is provided as an array
, the first value must be the path
of an other field which value should be watched. The second is an operator that defines the type of comparison. The third is the expected value of the other field.
<MatrixElement name="field" :conditions="[['other_field', '==', 'expected_value']]" ... />
Hint: In case you want to check for equality you might leave the operator and pass the expected value as the second param:
<MatrixElement name="field" :conditions="[['other_field', 'expected_value']]" ... />
Available operators:
==
- expect equality!=
- expect inequality>
- expect the other element's value(s) to be higher>=
- expect the other element's value(s) to be higher or equal<
- expect the other element's value(s) to be lower<=
- expect the other element's value(s) to be lower or equal^
- expect the other element's value to start with$
- expect the other element's value to end with*
- expect the other element's value to containin
- expect to be among an array of valuesnot_in
- expect not to be among an array of valuestoday
- expect to be todaybefore
- expect to be before a date (value can be aYYYY-MM-DD
date string ortoday
)after
- expect to be after a date (value can be aYYYY-MM-DD
date string ortoday
)
The expected value can also be defined as an array
in which case any of its values will fulfill the condition.
Conditions can be defined with OR
relation or as function
. Learn more about conditions here.
columns
- Type:
object|string|number
- Default:
null
<MatrixElement label="Label" :columns="{ container: 12, label: 3, wrapper: 12 }" ... />
Sets the size of the container
, label
and wrapper
using the theme's grid system, where the:
container
is the outermost DOM that contains bothlabel
andwrapper
label
contains the labelwrapper
contains the matrix.
container: 12
label: 3
wrapper: 12
The value of container
defines the size of the element's container. 12
will result in full width, 6
in half, 4
in third and so on.
The value of label
defines the amount of space the label should take up within the container. If the container
is 12
and label
is 6
the label is going to take up half the space and the matrix will the other half (which is calculated automatically). If the container
is 6
and label
is 6
, the label will only take up one forth and the matrix the rest. In case the label
has full width (12
) the matrix will also take up full space instead of becoming zero.
The value of wrapper
defines the size of the matrix wrapper within the space left for it in the container after subtracting the size of the label. If the container
is 12
and label
is 4
the space left for the matrix is 8
. In this case if the wrapper
value is 12
it will take up the full space left for it (which is 8
) while if it is changed to 6
it will only take up half the space left for it (4
):
<MatrixElement label="Label" :columns="{ container: 12, label: 4, wrapper: 12 }" ... />
<MatrixElement label="Label" :columns="{ container: 12, label: 4, wrapper: 6 }" ... />
Note that while the size of the matrix wrapper changes, the size of extras like a description or error won't be limited to the wrapper's space. Instead it will take up the full space in the container left after subtracting the size of the label:
<MatrixElement
label="Label"
:columns="{ container: 12, label: 4, wrapper: 6 }"
description="Lorem ipsum dolor sit amet, consectetur adipiscing elit"
... />
You can set the value of columns
as a number
in which case the container
will receive its value without affecting the default settings of label
and wrapper
:
<MatrixElement label="Label" :columns="6" ... /> <!-- { container: 6, label: 3, wrapper: 12 } -->
You can as well define column values for different breakpoints using the theme system's breakpoints like sm
, md
, etc. as keys:
<MatrixElement label="Label" :columns="{
xs: { container: 12, label: 12, wrapper: 12 },
sm: { container: 12, label: 4, wrapper: 12 },
md: 12,
lg: { container: 12, label: 2, wrapper: 12 }
}" ... />
Default column sizes can be defined globally in
vueform.config.js
or on form level usingcolumns
.
inline
- Type:
boolean
- Default:
false
<MatrixElement :inline="true" ... />
Renders the element and all of its components in a single <span>
without applying columns
.
size
- Type:
string
- Default:
undefined
<MatrixElement size="sm" ... />
<MatrixElement ... /> <!-- Default size: 'md' -->
<MatrixElement size="lg" ... />
The size of the element and its child components.
view
- Type:
string
- Default:
undefined
<MatrixElement view="alt" ... />
The name of the view to be used for the element and by default for its child components. If undefined
the default view will be used. Child component views can be overridden with views
option.
Learn more about views here.
views
- Type:
object
- Default:
{}
<MatrixElement :views="{
ComponentName: 'alt'
}" ... />
The name of the views for the child components.
Learn more about views here.
addClasses
- Type:
object|function
- Default:
{}
<MatrixElement :add-classes="{
ComponentName: {
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}
}" ... />
Adds classes to any component's class names. The classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :add-classes="(form$) => ({
ComponentName: {
classname: [
{ 'class-value': form$.el$('other_field')?.value === 'some_value' }
],
}
})" ... />
Learn more about adding classes here.
addClass
- Type:
array|object|string|function
- Default:
null
<MatrixElement :add-class="{
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}" ... />
Adds classes to any of MatrixElement
component's class names. Classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :add-class="(form$) => ({
classname: [
{ 'class-value': form$.el$('other_field')?.value === 'some_value' }
],
})" ... />
Learn more about adding classes here.
removeClasses
- Type:
object|function
- Default:
{}
<MatrixElement :remove-classes="{
ComponentName: {
classname: ['class-value-1', 'class-value-2']
}
}" ... />
Removes classes from any class names of any components. The classes to be removed must be listed in an array
.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :remove-classes="(form$) => ({
ComponentName: {
classname: form$.el$('other_field')?.value === 'some_value'
? ['class-value-1', 'class-value-2']
: [],
}
})" ... />
Learn more about removing classes here.
removeClass
- Type:
array|object|function
- Default:
null
<MatrixElement :remove-class="{
classname: ['class-value-1', 'class-value-2']
}" ... />
Removes classes from any of MatrixElement
component's class names. The classes to be removed must be listed in an array
.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :remove-class="(form$) => ({
classname: form$.el$('other_field')?.value === 'some_value'
? ['class-value-1', 'class-value-2']
: [],
})" ... />
Learn more about removing classes here.
replaceClasses
- Type:
object|function
- Default:
{}
<MatrixElement :replace-classes="{
ComponentName: {
classname: {
'from-class': 'to-class',
'from-class': ['to-class'],
'from-class': [{'to-class': true}],
}
}
}" ... />
Replaces classes of any class names of any component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string
or an array
. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :replace-classes="(form$) => ({
ComponentName: {
classname: form$.el$('other_field')?.value === 'some_value' ? {
'from-class': 'to-class'
} : {},
}
})" ... />
Learn more about replacing classes here.
replaceClass
- Type:
object|function
- Default:
null
<MatrixElement :replace-class="{
classname: {
'from-class': 'to-class',
'from-class': ['to-class'],
'from-class': [{'to-class': true}],
}
}" ... />
Replaces the classes of any class names of MatrixElement
component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string
or an array
. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :replace-class="(form$) => ({
classname: form$.el$('other_field')?.value === 'some_value' ? {
'from-class': 'to-class'
} : {},
})" ... />
Learn more about replacing classes here.
overrideClasses
- Type:
object|function
- Default:
{}
<MatrixElement :override-classes="{
ComponentName: {
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}
}" ... />
Overrides the classes of any component's class names. The classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :override-classes="(form$) => ({
ComponentName: form$.el$('other_field')?.value === 'some_value' ? {
classname: 'class-value'
} : {}
})" ... />
Learn more about overriding classes here.
overrideClass
- Type:
array|object|string|function
- Default:
null
<MatrixElement :override-classes="{
ComponentName: {
classname: 'class-value',
classname: ['class-value'],
classname: [{'class-value': true}],
}
}" ... />
Overrides the classes of any of MatrixElement
component's class names. The classes can have string
or array
values. When Vue style classes are used object
values must be wrapped in an array.
Conditional classes can be passed as a function
with form$
param, eg.:
<MatrixElement :override-class="(form$) => (form$.el$('other_field')?.value === 'some_value' ? {
classname: 'class-value'
} : {})" ... />
Learn more about overriding classes here.
templates
- Type:
object
- Default:
{}
<template>
<div id="app">
<Vueform>
<MatrixElement :templates="{ ElementError }" ... />
</Vueform>
</div>
</template>
<script>
import { markRaw } from 'vue'
import CustomElementError from './CustomElementError.vue'
export default {
data() {
return {
ElementError: markRaw(CustomElementError),
}
}
}
</script>
Overrides templates used by the component.
Learn more about overriding templates here.
presets
- Type:
array
- Default:
[]
<MatrixElement :presets="['preset1', 'preset2']" ... />
The presets to be applied for the component.
Learn more about presets classes here.
slots
- Type:
object
- Default:
{}
<script>
import { Vueform, useVueform } from '@vueform/vueform';
import CustomDescriptionSlot from 'path/to/CustomDescriptionSlot.vue';
export default {
mixins: [Vueform],
setup: useVueform,
data: () => ({
vueform: {
schema: {
element: {
type: 'matrix',
slots: {
label: '<span>Label</span>',
description: CustomDescriptionSlot,
}
}
}
}
})
}
</script>
With this option you can define slot values in a schema based form that you would normally just write inline. The value of a slot can be a plain string, HTML or a component with render function.
While this option can be also used in inline forms, it's primarily intended for schema based forms.
Properties
Properties include data
, computed
and inject
properties of the component. You can use them by reaching the element's Vue component instance via form$
's el$(path)
method or directly via this
in options API or el$
in Composition API.
rowsCount
- Type:
number
- Group:
data
The count of current rows when rows are dynamic.
cells$
- Type:
object
- Group:
data
The instances of cells.
grid
- Type:
HTMLElement
- Group:
data
The HTML element of the matrix grix.
aria
- Type:
object
- Group:
computed
The aria-*
attributes of the input.
hasDynamicRows
- Type:
boolean
- Group:
computed
Whether the matrix has dynamic rows.
computedRows
- Type:
number|array
- Group:
computed
The value of rows
or rowsCount
if rows are dynamic.
resolvedRows
- Type:
array
- Group:
computed
The rows of the matrix to be displayed.
resolvedColumns
- Type:
array
- Group:
computed
The columns of the matrix to be displayed.
dataType
- Type:
array
- Group:
computed
The data structure type of the matrix. Can be: assoc
, array
or object
.
addLabel
- Type:
string
- Group:
computed
The label of add button.
rowsVisible
- Type:
boolean
- Group:
computed
Whether row labels should be displayed.
colsVisible
- Type:
boolean
- Group:
computed
Whether column headers should be displayed.
allowAdd
- Type:
boolean
- Group:
computed
Whether rows can be added when rows are dynamic.
allowRemove
- Type:
boolean
- Group:
computed
Whether rows can be removed when rows are dynamic.
cells
- Type:
array
- Group:
computed
The component props of the cells.
inputTypes
- Type:
array
- Group:
computed
The array of cell input types.
isReadonly
- Type:
boolean
- Group:
computed
Whether the element is readonly.
isRequired
- Type:
boolean
- Group:
computed
Whether the element is required (has required rule).
useCustomFilled
- Type:
boolean
- Group:
computed
Whether the element should use a custom logic for checking if it is filled when validating.
isFilled
- Type:
boolean
- Group:
computed
Whether the element is filled is useCustomFilled
is true
.
isDefault
- Type:
boolean
- Group:
computed
Whether the element has its default value.
value
- Type:
any
- Group:
computed
The value of the element.
model
- Type:
any
- Group:
computed
Intermediary value between element's value and field's v-model
. It is required when we need to transform the value format between the element and its field.
data
- Type:
object
- Group:
computed
The value of the element in {[name]: value}
value format. This gets merged with the parent component's data.
requestData
- Type:
object
- Group:
computed
Same as data
property except that it only includes the element's value if submit
is not disabled and available
is true
(has no conditions
or they are fulfilled).
path
- Type:
string
- Group:
computed
The path of the element using dot .
syntax.
dataPath
- Type:
string
- Group:
computed
The path of the element's data using dot .
syntax.
parent
- Type:
VNode
- Group:
computed
The parent component of the element.
children$
- Type:
object
- Group:
computed
Child element components.
validated
- Type:
boolean
- Group:
computed
Whether the element was already validated at least once.
invalid
- Type:
boolean
- Group:
computed
Whether the element has any failing rules.
dirty
- Type:
boolean
- Group:
computed
Whether the element's value was modified.
pending
- Type:
boolean
- Group:
computed
Whether the element has any async rules in progress.
busy
- Type:
boolean
- Group:
computed
Whether the element is pending
.
messageBag
- Type:
MessageBag
- Default:
MessageBag
- Group:
data
Instance of MessageBag service. Custom errors and messages can be added.
errors
- Type:
array
- Group:
computed
All the errors of MessageBag
.
error
- Type:
string
- Group:
computed
The first error of MessageBag
.
available
- Type:
boolean
- Group:
computed
Whether no conditions
are defined or they are all fulfilled.
hidden
- Type:
boolean
- Default:
false
- Group:
data
visible
- Type:
boolean
- Group:
computed
Whether the element is visible. It's false
when available
or active
is false
or hidden
is true
.
isDisabled
- Type:
boolean
- Group:
computed
Whether the element is disabled.
container
- Type:
HTMLElement
- Group:
data
The ref to the outermost DOM of the element.
fieldId
- Type:
string
- Group:
computed
hasLabel
- Type:
boolean
- Group:
computed
Whether the element has a label
option, a #label slot or Vueform
component's forceLabels
option is true
.
Size
- Type:
string
- Group:
computed
The resolved size of the element and all of its child components.
View
- Type:
string
- Group:
computed
The name of the resolved view for the component and the default view for its child components. Child component views can be overridden with views
option. This one should be used to determine the component's view in class functions.
template
- Type:
object
- Group:
computed
The component's template.
classes
- Type:
object
- Group:
computed
The component's classes.
theme
- Type:
object
- Group:
inject
The global theme object, which contains all the default templates and classes.
form$
- Type:
Vueform
- Group:
inject
The root form's component.
el$
- Type:
VueformElement
- Group:
computed
The element's component.
mounted
- Type:
boolean
- Default:
true
- Group:
data
Whether the element has been already mounted.
Methods
The methods
of the component that you can use by reaching the element's Vue component instance via form$
's el$(path)
method or directly via this
in options API or el$
in Composition API.
resolveComponentType
- Arguments:
{object} column*
- the column definition object
- Returns:
string
Resolves the cell component type (for :is
) based on a column object.
resolveComponentProps
- Arguments:
{object} row*
- the row definition object{object} col*
- the column definition object{number} rowIndex*
- the index of the row{number} colIndex*
- the index of the column
- Returns:
object
Resolves the cell component properties.
resolveComponentName
- Arguments:
{number} rowIndex*
- the index of the row{number} colIndex*
- the index of the column
- Returns:
string
Resolves the cell component name based on row and column index.
getColStyle
- Arguments:
{object} index*
- the index of the column
- Returns:
object
Returns the style of a colum based on its index.
resolveColInputType
- Arguments:
{object} col*
- the column definition object
- Returns:
object|string
Resolves the input type of a column.
resolveColConditions
- Arguments:
{object} row*
- the row definition object{object} col*
- the column definition object
- Returns:
object
Resolves the conditions of a cell based on row and column.
resolveColType
- Arguments:
{object} col*
- the column definition object
- Returns:
string
Resolves the type of the input field of a column.
clearMessages
- Returns:
void
Clears the manually added messages from the messageBag
.
load
- Arguments:
{any} value*
- the value to be loaded{boolean} format*
- whether the loaded value should be formatted withformatLoad
before setting the value of the element (default:false
)
- Returns:
void
Loads value to the element using optional formatLoad
formatter. This is the method that gets called for each element when loading data to the form with format: true
.
update
- Arguments:
{any} value*
- the value to be set
- Returns:
void
Updates the value of the element similarly to load
, only that it can't format data.
clear
- Returns:
void
Clears the element's value.
reset
- Returns:
void
Resets the element's value to default
(or empty if default
is not provided). Also resets all the validation state for the element.
disable
- Returns:
void
Disables the element.
enable
- Returns:
void
Enables the element even if it is disabled by disabled
option.
on
- Arguments:
{string} event*
- name of the event to listen for{function} callback*
- callback to run when the event is triggered
- Returns:
void
Adds a listener for an event.
off
- Arguments:
{string} event*
- name of the event to remove
- Returns:
void
Removes all listeners for an event.
fire
- Arguments:
{any} args*
- list of arguments to pass over to the event callback
- Returns:
void
Fires and emits an event.
validate
- Returns:
Promise
Checks each validation rule for the element (async).
clean
- Returns:
void
Removes the element's dirty
state.
resetValidators
- Returns:
void
Sets the validators to default state.
reinitValidation
- Returns:
void
Re-initializes validators when rules have changed.
hide
- Returns:
void
Hides the element.
show
- Returns:
void
Shows the element if it was hidden with hide()
method.
Events
With events you can subscribe to different events broadcasted by the element. It can be used inline as regular Vue event listeners with @event
format. In schema
it can be used in PascalCase format prefixed with on
(eg. onChange
).
<template>
<Vueform>
<MatrixElement @{eventName}="handler" ... />
</Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'
export default {
mixins: [Vueform],
setup: useVueform,
data: () => ({
vueform: {
schema: {
element: {
type: 'matrix',
on{EventName}() {
// ...
}
}
}
}
})
}
</script>
You can also use on(event, callback)
method to subscribe to events.
change
- Params:
{string} newValue
- the new value{string} oldValue
- the old value{component} el$
- the element's component
Triggered when the element's value is changed.
add
- Params:
{number} index
- the index of the added row{array} newValue
- the element's value after the row is added{array} oldValue
- the element's value before the row is added{component} el$
- the element's component
Triggered when a new row is added.
remove
- Params:
{number} index
- the index of the removed item{array} newValue
- the element's value after the row is removed{array} oldValue
- the element's value before the row is removed{component} el$
- the element's component
Triggered when a row is removed.
beforeCreate
- Params:
{component} el$
- the element's component
Triggered in beforeCreate hook.
created
- Params:
{component} el$
- the element's component
Triggered in created hook.
beforeMount
- Params:
{component} el$
- the element's component
Triggered in beforeMount hook.
mounted
- Params:
{component} el$
- the element's component
Triggered in mounted hook.
beforeUpdate
- Params:
{component} el$
- the element's component
Triggered in beforeUpdate hook.
updated
- Params:
{component} el$
- the element's component
Triggered in updated hook.
beforeUnmount
- Params:
{component} el$
- the element's component
Triggered in beforeUnmount (or beforeDestroy in Vue 2) hook.
unmounted
- Params:
{component} el$
- the element's component
Triggered in unmounted (or destroyed in Vue 2) hook.
Slots
Slots can be used inline or in slots
option object when used in schema
:
<template>
<Vueform>
<MatrixElement ... >
<template #{slot-name}="scope">
<!-- ... --->
</template>
</MatrixElement>
</Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'
export default {
mixins: [Vueform],
setup: useVueform,
data: () => ({
vueform: {
schema: {
element: {
type: 'matrix',
slots: {
{slotName}: // implementation
}
}
}
}
})
}
</script>
label
- Scope:
{component} el$
- the element's component
Renders a label for the element in ElementLabel
component.
info
- Scope:
{component} el$
- the element's component
Renders an info icon in ElementInfo
component next the the element label. When the icon is hovered it shows the content of this slot. The element needs to have a label to render this.
required
description
- Scope:
{component} el$
- the element's component
Renders description for the element in ElementDescription
component.
before
- Scope:
{component} el$
- the element's component
Renders an ElementText
component before the matrix.
between
- Scope:
{component} el$
- the element's component
Renders an ElementText
component after the matrix and before description.
after
- Scope:
{component} el$
- the element's component
Renders an ElementText
component after the description and error.