Appearance

VfMatrix ​

Basic ​

The default mode is 'auto', which renders a text input in each cell. Rows are group containers and columns define the fields within each row. The matrix value is an object where keys are row values and values are nested objects with column values as keys and the cell input values as values.

Q1
Q2
Marketing
Engineering
vue
<VfMatrix
  name="budget"
  :cols="['Q1', 'Q2']"
  :rows="['Marketing', 'Engineering']"
/>
vue
<template>
  <VfMatrix
    name="budget"
    :cols="['Q1', 'Q2']"
    :rows="['Marketing', 'Engineering']"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  budget: {
    type: 'matrix',
    cols: ['Q1', 'Q2'],
    rows: ['Marketing', 'Engineering'],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Single Mode ​
The mode="single" turns each row into a radio group where only one column value can be selected per row. The matrix value is an object where keys are row values and each value is the selected column's value.
Poor
Fair
Good
Excellent
Price
Quality
vue
<VfMatrix
  name="satisfaction"
  :cols="['Poor', 'Fair', 'Good', 'Excellent']"
  :rows="['Price', 'Quality']"
  mode="single"
/>
vue
<template>
  <VfMatrix
    name="satisfaction"
    :cols="['Poor', 'Fair', 'Good', 'Excellent']"
    :rows="['Price', 'Quality']"
    mode="single"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  satisfaction: {
    type: 'matrix',
    cols: ['Poor', 'Fair', 'Good', 'Excellent'],
    rows: ['Price', 'Quality'],
    mode: 'single',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Multiple Mode ​
The mode="multiple" turns each row into a checkbox group where multiple column values can be selected per row. The matrix value is an object where keys are row values and each value is an array of selected column values.
Create
Read
Update
Admin
Editor
vue
<VfMatrix
  name="permissions"
  :cols="['Create', 'Read', 'Update']"
  :rows="['Admin', 'Editor']"
  mode="multiple"
/>
vue
<template>
  <VfMatrix
    name="permissions"
    :cols="['Create', 'Read', 'Update']"
    :rows="['Admin', 'Editor']"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  permissions: {
    type: 'matrix',
    cols: ['Create', 'Read', 'Update'],
    rows: ['Admin', 'Editor'],
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Plain Object ​
The rows and cols props also accept a plain object where keys are used as values and values as labels.
Friday
Saturday
Sunday
Morning
Afternoon
Evening
vue
<VfMatrix
  name="availability"
  :cols="{
    fri: 'Friday',
    sat: 'Saturday',
    sun: 'Sunday',
  }"
  :rows="{
    morning: 'Morning',
    afternoon: 'Afternoon',
    evening: 'Evening'
  }"
/>
vue
<template>
  <VfMatrix
    name="availability"
    :cols="{
      fri: 'Friday',
      sat: 'Saturday',
      sun: 'Sunday',
    }"
    :rows="{
      morning: 'Morning',
      afternoon: 'Afternoon',
      evening: 'Evening'
    }"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  availability: {
    type: 'matrix',
      cols: {
      fri: 'Friday',
      sat: 'Saturday',
      sun: 'Sunday',
    },
    rows: {
      morning: 'Morning',
      afternoon: 'Afternoon',
      evening: 'Evening'
    },
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Array of Objects ​
The rows and cols props can also be an array of objects. Each object's value property is used as the value and its label property as the label by default. To read them from different properties, set rowValue, rowLabel, colValue, and colLabel accordingly. These props also accept a function that receives the row or column object and returns the resolved value or label.
Friday
Saturday
Sunday
Morning
Afternoon
Evening
vue
<VfMatrix
  name="schedule"
  :cols="[
    { id: 'fri', day: 'Friday' },
    { id: 'sat', day: 'Saturday' },
    { id: 'sun', day: 'Sunday' },
  ]"
  col-value="id"
  col-label="day"
  :rows="[
    { code: 'am', slot: 'Morning' },
    { code: 'pm', slot: 'Afternoon' },
    { code: 'ev', slot: 'Evening' },
  ]"
  row-value="code"
  row-label="slot"
/>
vue
<template>
  <VfMatrix
    name="schedule"
    :cols="[
      { id: 'fri', day: 'Friday' },
      { id: 'sat', day: 'Saturday' },
      { id: 'sun', day: 'Sunday' },
    ]"
    col-value="id"
    col-label="day"
    :rows="[
      { code: 'am', slot: 'Morning' },
      { code: 'pm', slot: 'Afternoon' },
      { code: 'ev', slot: 'Evening' },
    ]"
    row-value="code"
    row-label="slot"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  schedule: {
    type: 'matrix',
    cols: [
      { id: 'fri', day: 'Friday' },
      { id: 'sat', day: 'Saturday' },
      { id: 'sun', day: 'Sunday' },
    ],
    colValue: 'id',
    colLabel: 'day',
    rows: [
      { code: 'am', slot: 'Morning' },
      { code: 'pm', slot: 'Afternoon' },
      { code: 'ev', slot: 'Evening' },
    ],
    rowValue: 'code',
    rowLabel: 'slot',
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Object Value ​
In 'single' and 'multiple' modes, setting colValue to null makes the selected values the full column objects instead of a single property.
Mode:
Friday
Saturday
Sunday
Morning
Afternoon
Evening
vue
<VfMatrix name="schedule" :col-value="null" :cols="[
  { id: 'fri', day: 'Friday' },
  { id: 'sat', day: 'Saturday' },
  { id: 'sun', day: 'Sunday' },
]" />
vue
<script setup lang="ts">
import { ref } from 'vue'

const mode = ref('single')
</script>
<template>
  <VfSelect
    v-model="mode"
    name="mode"
    :items="{ single: 'Single', multiple: 'Multiple' }"
    default="multiple"
    addon-before="Mode:"
    stacked
  />
  <VfMatrix
    name="schedule"
    :cols="[
      { id: 'fri', day: 'Friday' },
      { id: 'sat', day: 'Saturday' },
      { id: 'sun', day: 'Sunday' },
    ]"
    :col-value="null"
    col-label="day"
    :rows="['Morning', 'Afternoon', 'Evening']"
    :mode="mode"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'
import { ref, computed } from 'vue'

const mode = ref('single')

const schema = comnputed(() => defineSchema({
  mode: {
    type: 'select',
    items: { single: 'Single', multiple: 'Multiple' },
    addonBefore: 'Mode:',
    default: 'multiple',
    stacked: true,
  },
  schedule: {
    type: 'matrix',
    cols: [
      { id: 'fri', day: 'Friday' },
      { id: 'sat', day: 'Saturday' },
      { id: 'sun', day: 'Sunday' },
    ],
    colValue: null,
    colLabel: 'day',
    rows: ['Morning', 'Afternoon', 'Evening'],
    mode: mode.value,
  },
}))

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Async Function ​
The rows and cols props can be an async function that returns the items. The function receives the component context as its argument.
vue
<VfMatrix
  name="skills"
  :cols="async () => {
    const { data } = await $http.get('/data/users.json')
    return data
  }"
  :rows="async () => {
    const { data } = await $http.get('/data/skills.json')
    return data
  }"
/>
vue
<script setup lang="ts">
import { useHttp } from '@vueform/ui'

const $http = useHttp()
</script>
<template>
  <VfMatrix
    name="skills"
    :cols="async () => {
      const { data } = await $http.get('/data/users.json')
      return data
    }"
    :rows="async () => {
      const { data } = await $http.get('/data/skills.json')
      return data
    }"
    mode="single"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm, useHttp } from '@vueform/ui'

const $http = useHttp()

const schema = defineSchema({
  skills: {
    type: 'matrix',
    cols: async () => {
      const { data } = await $http.get('/data/users.json')
      return data
    },
    rows: async () => {
      const { data } = await $http.get('/data/skills.json')
      return data
    },
    mode: 'single',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Retriggering ​
Use colsTrigger and rowsTrigger to re-resolve the async functions when specific element values change. They accept an array of element paths to watch. The colsDebounce and rowsDebounce props add a delay (in ms) before re-fetching.
vue
<VfSelect
  name="department"
  :items="['Engineering', 'Design', 'Marketing']"
/>
<VfMatrix
  name="skills"
  :cols="async () => {
    const { data } = await $http.get('/data/skills.json')
    return data
  }"
  :rows=" async ({ form$ }) => {
    const { data } = await $http.get(
      `/data/users-${form$.model.department}.json`
    )
    return data
  }"
  :rows-trigger="['department']"
  :rows-debounce="300"
/>
vue
<script setup lang="ts">
import { useHttp } from '@vueform/ui'

const $http = useHttp()
</script>
<template>
  <VfSelect
    name="department"
    label="Department"
    :items="['Engineering', 'Design', 'Marketing']"
    default="Engineering"
  />
  <VfMatrix
    name="skills"
    :cols="async () => {
      const { data } = await $http.get('/data/skills.json')
      return data
    }"
    :rows=" async ({ form$ }) => {
      const { data } = await $http.get(
        `/data/users-${form$.model.department}.json`
      )
      return data
    }"
    :rows-trigger="['department']"
    :rows-debounce="300"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm, useHttp } from '@vueform/ui'

const $http = useHttp()

const schema = defineSchema({
  department: {
    type: 'select',
    label: 'Department',
    items: ['Engineering', 'Design', 'Marketing'],
    default: 'Engineering',
  },
  skills: {
    type: 'matrix',
    cols: async () => {
      const { data } = await $http.get('/data/skills.json')
      return data
    },
    rows: async ({ form$ }) => {
      const { data } = await $http.get(`/data/users-${form$.model.department}.json`)
      return data
    },
    rowsTrigger: ['department'],
    rowsDebounce: 300,
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Endpoints ​
The rows and cols props also accept an endpoint URL string. Expressions within the string are resolved reactively — when a referenced value changes, the endpoint is re-fetched automatically.
vue
<VfSelect
  name="department"
  :items="['Engineering', 'Design', 'Marketing']"
/>
<VfMatrix
  name="skills"
  cols="/data/skills.json"
  rows="/data/users-{department}.json"
/>
vue
<template>
  <VfSelect
    name="department"
    label="Department"
    :items="['Engineering', 'Design', 'Marketing']"
    default="Engineering"
  />
  <VfMatrix
    name="skills"
    cols="/data/skills.json"
    rows="/data/users-{department}.json"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  department: {
    type: 'select',
    label: 'Department',
    items: ['Engineering', 'Design', 'Marketing'],
    default: 'Engineering',
  },
  skills: {
    type: 'matrix',
    cols: '/data/skills.json',
    rows: '/data/users-{department}.json',
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
endpoint Prop ​
Alternatively, use the endpoint prop to load both cols and rows from a single request. The response is expected to contain cols and rows keys by default — use colsKey and rowsKey to customize. The method and headers props apply to all endpoint requests.
vue
<VfMatrix
  name="skills"
  endpoint="/data/matrix.json"
  cols-key="skills"
  rows-key="users"
  method="GET"
  :headers="{ 'X-Custom': 'value' }"
/>
vue
<template>
  <VfMatrix
    name="skills"
    endpoint="/data/matrix.json"
    cols-key="skills"
    rows-key="users"
    method="GET"
    :headers="{ 'X-Custom': 'value' }"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  skills: {
    type: 'matrix',
    endpoint: '/data/matrix.json',
    colsKey: 'skills',
    rowsKey: 'users',
    method: 'GET',
    headers: { 'X-Custom': 'value' },
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Transformers ​
The transformEndpoint function reshapes the endpoint response before cols and rows are extracted. Similarly, transformCols and transformRows can transform data from their respective endpoint string sources.
vue
<VfMatrix
  name="skills"
  endpoint="/data/matrix-data.json"
  :transform-endpoint="(data) => ({
    cols: data?.data?.skills?.map((c: any) => ({ value: c.id, label: c.title })) || [],
    rows: data?.data?.team?.map((u: any) => ({ value: u.id, label: u.name })) || [],
  })"
/>
vue
<template>
  <VfMatrix
    name="skills"
    endpoint="/data/matrix-data.json"
    :transform-endpoint="(data) => ({
        cols: data?.data?.skills?.map((c: any) => ({ value: c.id, label: c.title })) || [],
        rows: data?.data?.team?.map((u: any) => ({ value: u.id, label: u.name })) || [],
    })"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  skills: {
    type: 'matrix',
    endpoint: '/data/matrix-data.json',
    transformEndpoint: (data) => ({
      cols: data?.data?.skills?.map((c: any) => ({ value: c.id, label: c.title })) || [],
      rows: data?.data?.team?.map((u: any) => ({ value: u.id, label: u.name })) || [],
    }),
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Custom Columns ​
In 'auto' mode, columns can override the default text input by providing a schema property with an element definition.
SKU
Qty
Status
Widget
Gadgets
vue
<VfMatrix name="inventory" :cols="[
  { value: 'sku', label: 'SKU' },
  { value: 'qty', label: 'Qty' },
  {
    value: 'status',
    label: 'Status',
    schema: {
      type: 'select',
      items: ['In Stock', 'Low', 'Out of Stock'],
      placeholder: 'Select',
    },
  },
]" />
vue
<template>
  <VfMatrix
    name="inventory"
    :rows="['Widget', 'Gadgets']"
    :cols="[
      { value: 'sku', label: 'SKU' },
      { value: 'qty', label: 'Qty' },
      {
        value: 'status',
        label: 'Status',
        schema: {
          type: 'select',
          items: ['In Stock', 'Low', 'Out of Stock'],
          placeholder: 'Select',
        },
      },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  inventory: {
    type: 'matrix',
    rows: ['Widget', 'Gadgets'],
    cols: [
      { value: 'sku', label: 'SKU' },
      { value: 'qty', label: 'Qty' },
      {
        value: 'status',
        label: 'Status',
        schema: {
          type: 'select',
          items: ['In Stock', 'Low', 'Out of Stock'],
          placeholder: 'Select',
        },
      },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Conditions ​
When rows and cols are arrays of objects, each item can define a conditions property. The row or column is only displayed when its conditions are met.
Email
SMS
News
Updates
vue
<VfMatrix
  name="notifications"
  :cols="[
    { value: 'email', label: 'Email' },
    { value: 'sms', label: 'SMS' },
    { value: 'push', label: 'Push', conditions: [['premium', '==', true]] },
  ]"
  :rows="[
    { value: 'news', label: 'News' },
    { value: 'updates', label: 'Updates' },
    { value: 'offers', label: 'Offers', conditions: [['premium', '==', true]] },
  ]"
/>
vue
<template>
  <VfCheckbox name="premium" text="Premium plan" />
  <VfMatrix
    name="notifications"
    :cols="[
      { value: 'email', label: 'Email' },
      { value: 'sms', label: 'SMS' },
      { value: 'push', label: 'Push', conditions: [['premium', '==', true]] },
    ]"
    :rows="[
      { value: 'news', label: 'News' },
      { value: 'updates', label: 'Updates' },
      { value: 'offers', label: 'Offers', conditions: [['premium', '==', true]] },
    ]"
    mode="multiple"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  premium: {
    type: 'checkbox',
    text: 'Premium plan',
  },
  notifications: {
    type: 'matrix',
    cols: [
      { value: 'email', label: 'Email' },
      { value: 'sms', label: 'SMS' },
      { value: 'push', label: 'Push', conditions: [['premium', '==', true]] },
    ],
    rows: [
      { value: 'news', label: 'News' },
      { value: 'updates', label: 'Updates' },
      { value: 'offers', label: 'Offers', conditions: [['premium', '==', true]] },
    ],
    mode: 'multiple',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Dynamic Rows ​
When rows is a number (or omitted), the matrix becomes dynamic — users can add and remove rows. The add and remove buttons are shown automatically.
Item
Qty
Price
1
2
vue
<VfMatrix name="items" :cols="['Item', 'Qty', 'Price']" :rows="2" />
vue
<template>
  <VfMatrix name="items" :cols="['Item', 'Qty', 'Price']" :rows="2" />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  items: {
    type: 'matrix',
    cols: ['Item', 'Qty', 'Price'],
    rows: 2,
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Row Limits ​
The min and max props constrain how many rows a dynamic matrix can have. The add button hides when max is reached; the remove button hides when min is reached.
Task
Priority
1
2
vue
<VfMatrix name="tasks" :rows="2" :min="1" :max="3"/>
vue
<template>
  <VfMatrix
    name="tasks"
    :rows="2"
    :min="1"
    :max="3"
    :cols="['Task', 'Priority']"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  tasks: {
    type: 'matrix',
    rows: 2,
    min: 1,
    max: 3,
    cols: ['Task', 'Priority'],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Sorting ​
The sort prop enables drag-and-drop row reordering on dynamic matrices.
Taks
Status
1
2
3
vue
<VfMatrix name="priorities" :rows="3" sort />
vue
<template>
  <VfMatrix
    name="priorities"
    :rows="3"
    sort
    :cols="['Taks', 'Status']"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  priorities: {
    type: 'matrix',
    rows: 3,
    sort: true,
    cols: ['Taks', 'Status'],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Tabular ​
The tabular prop renders the matrix as a bordered table with distinct header backgrounds and rounded corners.
Morning
Afternoon
Evening
Monday
Tuesday
Wednesday
Thursday
Friday
vue
<VfMatrix name="availability" tabular />
vue
<template>
  <VfMatrix
    name="availability"
    tabular
    mode="multiple"
    :cols="{
      morning: 'Morning',
      afternoon: 'Afternoon',
      evening: 'Evening',
    }"
    :rows="{
      mon: 'Monday',
      tue: 'Tuesday',
      wed: 'Wednesday',
      thu: 'Thursday',
      fri: 'Friday',
    }"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  availability: {
    type: 'matrix',
    tabular: true,
    mode: 'multiple',
    cols: {
      morning: 'Morning',
      afternoon: 'Afternoon',
      evening: 'Evening',
    },
    rows: {
      mon: 'Monday',
      tue: 'Tuesday',
      wed: 'Wednesday',
      thu: 'Thursday',
      fri: 'Friday',
    },
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Scrollable ​
The scrollable prop enables horizontal scrolling when the matrix overflows. Use stickyCols to pin row headers and stickyRows to pin column headers while scrolling.
Q1
Q2
Q3
Q4
Q5
Q6
Q7
Q8
Revenue
Costs
Profit
vue
<VfMatrix name="quarterly" scrollable sticky-cols sticky-rows />
vue
<template>
  <VfMatrix
    name="quarterly"
    scrollable
    sticky-rows
    :cols="{
      q1: 'Q1',
      q2: 'Q2',
      q3: 'Q3',
      q4: 'Q4',
      q5: 'Q5',
      q6: 'Q6',
      q7: 'Q7',
      q8: 'Q8',
    }"
    :rows="{
      revenue: 'Revenue',
      costs: 'Costs',
      profit: 'Profit',
    }"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  quarterly: {
    type: 'matrix',
    scrollable: true,
    stickyRows: true,
    cols: {
      q1: 'Q1',
      q2: 'Q2',
      q3: 'Q3',
      q4: 'Q4',
      q5: 'Q5',
      q6: 'Q6',
      q7: 'Q7',
      q8: 'Q8',
    },
    rows: {
      revenue: 'Revenue',
      costs: 'Costs',
      profit: 'Profit',
    },
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Custom Labels ​
The addLabel and removeLabel props customize the text of the add and remove buttons in dynamic matrices. You can also use addIcon and removeIcon to change their icons.
Name
Email
Phone
1
vue
<VfMatrix name="contacts" add-label="New contact" remove-label="Remove" />
vue
<template>
  <VfMatrix
    name="contacts"
    :rows="1"
    add-label="New contact"
    remove-label="Remove"
    :cols="{ name: 'Name', email: 'Email', phone: 'Phone' }"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  contacts: {
    type: 'matrix',
    rows: 1,
    addLabel: 'New contact',
    removeLabel: 'Remove',
    cols: { name: 'Name', email: 'Email', phone: 'Phone' },
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Column Widths ​
The minWidth and maxWidth props set the default minimum and maximum width for all columns. When cols is an array of objects, individual columns can override these using minWidth and maxWidth properties — the colMinWidth and colMaxWidth props let you customize which property names to read.
SKU
Product Name
Qty
1
vue
<VfMatrix
  name="inventory"
  min-width="60px"
  max-width="200px"
  :cols="[
    { value: 'sku', label: 'SKU', },
    {
      value: 'name',
      label: 'Product Name',
      minWidth: '200px',
      maxWidth: '1fr',
    },
    { value: 'qty', label: 'Qty', },
  ]"
/>
vue
<template>
  <VfMatrix
    name="inventory"
    min-width="60px"
    max-width="200px"
    :cols="[
      { value: 'sku', label: 'SKU', },
      {
        value: 'name',
        label: 'Product Name',
        minWidth: '200px',
        maxWidth: '1fr',
      },
      { value: 'qty', label: 'Qty', },
    ]"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  inventory: {
    type: 'matrix',
    minWidth: '60px',
    maxWidth: '200px',
    cols: [
      { value: 'sku', label: 'SKU', },
      {
        value: 'name',
        label: 'Product Name',
        minWidth: '200px',
        maxWidth: '1fr',
      },
      { value: 'qty', label: 'Qty', },
    ],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Grid Template Columns ​
The gridTemplateColumns prop gives full control over the CSS grid-template-columns value. It accepts a string or a function that receives the component context and returns the value.
ID
Name
Email
1
vue
<VfMatrix
  name="data"
  :cols="['ID', 'Name', 'Email']"
  grid-template-columns="48px 1fr 1fr min-content"
/>
vue
<template>
  <VfMatrix
    name="data"
    :cols="['ID', 'Name', 'Email']"
    grid-template-columns="48px 1fr 1fr min-content"
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  data: {
    type: 'matrix',
    cols: ['ID', 'Name', 'Email'],
    gridTemplateColumns: '48px 1fr 1fr min-content',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Validation ​
Setting required rule on the matrix ensures that:
  • In 'auto' mode — all columns in every row must have a non-null value.
  • In 'single' and 'multiple' modes — at least one column must be selected per row.
Mode:
Email
SMS
Push
News
Updates
Offers
vue
<VfMatrix
  name="preferences"
  :cols="['Email', 'SMS', 'Push']"
  :rows="['News', 'Updates', 'Offers']"
  rules="required"
  :mode
/>
vue
<script setup lang="ts">
import { ref } from 'vue'

const mode = ref('single')
</script>
<template>
  <VfForm hide-errors>
    <VfSelect
      v-model="mode"
      name="mode"
      :items="{ single: 'Single', multiple: 'Multiple', auto: 'Auto' }"
      default="single"
      addon-before="Mode:"
      stacked
    />
    <VfMatrix
      name="preferences"
      :cols="['Email', 'SMS', 'Push']"
      :rows="['News', 'Updates', 'Offers']"
      :mode="mode"
      rules="required"
    />
    <VfButton type="submit" text="Submit" action="submit" />
  </VfForm>
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'
import { ref, computed } from 'vue'

const mode = ref('single')

const schema = defineSchema({
  mode: {
    type: 'select',
    items: { single: 'Single', multiple: 'Multiple', auto: 'Auto' },
    addonBefore: 'Mode:',
    default: 'single',
    stacked: true,
  },
  preferences: {
    type: 'matrix',
    cols: ['Email', 'SMS', 'Push'],
    rows: ['News', 'Updates', 'Offers'],
    mode: mode.value,
    rules: 'required',
  },
  submit: {
    type: 'button',
    text: 'Submit',
    action: 'submit',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Row Rules ​
To apply additional rules to individual rows, define them via the rules property on each row object (customizable via rowRules). Per-row rules like required, min, max, between, size, gt, lt, gte, and lte control the selection count for that specific row.
Email
SMS
Push
News
Updates
Offers
vue
<VfMatrix
  name="preferences"
  :cols="['Email', 'SMS', 'Push']"
  row-rules="validate"
  :rows="[
    { value: 'news', label: 'News', validate: 'required|min:2' },
    { value: 'updates', label: 'Updates', validate: 'required' },
    { value: 'offers', label: 'Offers' },
  ]"
  mode="multiple"
/>
vue
<template>
  <VfMatrix
    name="preferences"
    :cols="['Email', 'SMS', 'Push']"
    row-rules="validate"
    :rows="[
      { value: 'news', label: 'News', validate: 'required|min:2' },
      { value: 'updates', label: 'Updates', validate: 'required' },
      { value: 'offers', label: 'Offers' },
    ]"
    mode="multiple"
  />
  <VfButton type="submit" text="Submit" action="submit" />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  preferences: {
    type: 'matrix',
    cols: ['Email', 'SMS', 'Push'],
    rowRules: 'validate',
    rows: [
      { value: 'news', label: 'News', validate: 'required|min:2' },
      { value: 'updates', label: 'Updates', validate: 'required' },
      { value: 'offers', label: 'Offers' },
    ],
    mode: 'multiple',
  },
  submit: {
    type: 'button',
    text: 'Submit',
    action: 'submit',
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
For any other validation logic, you can create custom rules.
Disabled ​
The disabled prop prevents all interaction with the matrix. It also accepts Conditions.
Col A
Col B
Alpha
Beta
vue
<VfMatrix name="locked" disabled />
vue
<template>
  <VfMatrix
    name="locked"
    :rows="['Alpha', 'Beta']"
    :cols="['Col A', 'Col B']"
    disabled
  />
</template>
vue
<script setup lang="ts">
import { defineSchema, useForm } from '@vueform/ui'

const schema = defineSchema({
  locked: {
    type: 'matrix',
    disabled: true,
    rows: ['Alpha', 'Beta'],
    cols: ['Col A', 'Col B'],
  },
})

const [Form] = useForm({ schema })
</script>

<template>
  <Form />
</template>
Released under the MIT License.
Copyright © 2022-present Adam Berecz