Cards
Cards are the work items on your board - tasks, tickets, leads, whatever moves through columns. This guide covers how cards carry data, how the built-in layout decides what to show, and how you create, update, move, and delete cards through the action API.
Card data shape
A card is a plain object with an id and whatever fields your app needs. The widget reads a set of known field names for its built-in sections. You can attach any extra data for custom templates, filters, or sort comparators.
const cards = [
{
id: 1,
label: "Design homepage",
column: "todo",
description: "Create wireframes and mockups",
priority: 2,
progress: 0.3,
deadline: new Date("2026-08-01"),
tags: ["ui", "design"],
users: [1, 2],
attachments: 3,
comments: 5,
},
];
Every card needs an id. A card without one throws "Kanban cards must have an id" when the board loads its data.
The column field (or whatever key columnAccessor points to) determines which column a card belongs to. Everything else is optional - the built-in card hides any section whose data is missing.
deadline must be a Date. The board doesn't parse strings or timestamps, so convert them when you load data. RestDataProvider already does this for you:
const cards = raw.map(c => ({
...c,
deadline: c.deadline ? new Date(c.deadline) : null,
}));
Fields the built-in card layout reads:
- label - card title
- description - short text under the title
- priority - numeric id resolved against
card.priority.data - progress - fraction from 0 to 1
- deadline -
Date - tags - array of ids resolved against
card.tags.data - users - array of ids resolved against
card.users.data - attachments - count, or an array (its length is the count)
- comments - count, or an array (its length is the count)
- cover - image URL for the cover strip
- css - static CSS class(es) on the card wrapper
Section visibility (CardShape)
The card prop takes a CardShape object that controls which sections the built-in card renders. Each key is either a boolean toggle or an object with section-specific options.
<Kanban
:cards="cards"
:columns="columns"
:card="{
priority: true,
description: true,
progress: true,
deadline: true,
}"
/>

Omit a key or set it to false to hide the section. A section also won't render if the card object doesn't have data for it - CardShape is an upper bound on visibility, not a guarantee.
The default shape (returned by getCardShape()) enables priority, progress, description, deadline, and tags. Start from that default and adjust:
<script setup>
import { Kanban, getCardShape } from "@svar-ui/vue-kanban";
const card = { ...getCardShape(), users: { data: users }, menu: true };
</script>
<template>
<Kanban :cards="cards" :columns="columns" :card="card" />
</template>
Per-section options
Several sections take an options object instead of a plain boolean.
Priority
Pass a data array to map numeric ids to labels and colors:
<Kanban
:cards="cards"
:columns="columns"
:card="{
priority: {
data: [
{ id: 1, label: 'Low', css: 'wx-card-priority-low' },
{ id: 2, label: 'Medium', css: 'wx-card-priority-medium' },
{ id: 3, label: 'High', css: 'wx-card-priority-high' },
],
},
}"
/>
Without data, the card renders the raw priority value. Use getPriorityOptions() to start from the built-in Low / Medium / High list.
Tags
Pass a data array for label/color resolution and an optional max to cap visible tags:
:card="{
tags: {
max: 3,
data: [
{ id: 'docs', label: 'Docs', css: 'tag-docs' },
{ id: 'ui', label: 'UI', css: 'tag-ui' },
],
},
}"
Users
Pass a data array with optional avatar images, and max to limit visible avatars:
:card="{
users: {
max: 3,
data: [
{ id: 1, label: 'Alice', img: '/avatars/alice.png' },
{ id: 2, label: 'Bob' },
],
},
}"
When img isn't provided, the avatar shows initials derived from label.
Progress
progress is a fraction from 0 to 1. The bar renders only when the value is greater than 0. Set showLabel: true to display a percentage label next to the progress bar:
:card="{
progress: { showLabel: true },
}"
Deadline
With deadline: true, the date uses the active locale's formats.dateFormat - the same format the editor's date picker shows. To change it, pass format as a wx format string:
:card="{
deadline: { format: '%d/%m/%Y %H:%i' },
}"
For full control, pass a function that gets the Date and returns the text:
:card="{
deadline: { format: (date) => date.toLocaleDateString('en-GB') },
}"
Attachments and comments
Both are plain toggles. The card field can be a number or an array - for an array, the counter shows its length. The counter renders only when the count is greater than 0:
:card="{
attachments: true,
comments: true,
}"
Custom card body
When the built-in sections aren't enough, pass a Vue component as cardContent to replace the entire card body. The wrapper element (selection state, drag affordances, data-id attribute) stays intact - only the inner content is swapped.
<script setup>
import { Kanban } from "@svar-ui/vue-kanban";
import MyCard from "./MyCard.vue";
</script>
<template>
<Kanban :cards="cards" :columns="columns" :cardContent="MyCard" />
</template>
<!-- MyCard.vue -->
<script setup>
const props = defineProps({
card: { type: Object },
cardShape: { type: Object },
});
</script>
<template>
<div class="my-card">
<strong>{{ props.card.label }}</strong>
<span v-if="props.card.owner">{{ props.card.owner }}</span>
</div>
</template>
The component receives the source card object and the resolved cardShape, so you can still check the shape flags inside custom markup. The drag ghost renders the same component, so a dragged card looks the same as it does on the board.
Card styling
Two mechanisms apply CSS classes to cards.
Static class on the card object. Set a css field on individual cards:
const cards = [
{ id: 1, label: "Urgent fix", column: "doing", css: "card--urgent" },
];
Dynamic class via cardCss callback. Return a class string based on card data:
<Kanban
:cards="cards"
:columns="columns"
:cardCss="(card) =>
card.deadline && new Date(card.deadline) < new Date()
? 'card--overdue'
: ''"
/>
The two stack - the card wrapper gets both card.css and the cardCss return value. Column-level styling works the same way through columnCss.
Card menu
Set menu: true in the card shape to show a ⋯ button on each card. The button alone does nothing. The menu items and their handlers live on a CardActionMenu that wraps <Kanban>. Add a CardContextMenu around it to open the same menu on right click:
<script setup>
import { ref } from "vue";
import {
Kanban,
CardActionMenu,
CardContextMenu,
getMenuOptions,
} from "@svar-ui/vue-kanban";
const api = ref(null);
const options = [
...getMenuOptions(),
{ id: "archive", text: "Archive", icon: "wxi-archive" },
];
function onclick({ action }) {
if (action.id === "archive") {
// handle the custom action
}
}
</script>
<template>
<CardContextMenu :api="api" :options="options" :onclick="onclick">
<CardActionMenu :api="api" :options="options" :onclick="onclick">
<Kanban ref="api" :cards="cards" :columns="columns" :card="{ menu: true }" />
</CardActionMenu>
</CardContextMenu>
</template>

Without options, both wrappers use the built-in list from getMenuOptions() (Edit, Duplicate, Delete). The built-in ids (edit-card, duplicate-card, delete-card) run their store actions before onclick fires.
A custom cardContent replaces the built-in ⋯ button too. To keep it, render the exported CardMenuButton inside your component. It takes card and an optional css class, and opens the outer CardActionMenu:
<!-- MyCard.vue -->
<script setup>
import { CardMenuButton } from "@svar-ui/vue-kanban";
const props = defineProps({
card: { type: Object },
cardShape: { type: Object },
});
</script>
<template>
<div class="my-card">
<strong>{{ props.card.label }}</strong>
<CardMenuButton v-if="props.cardShape.menu" :card="props.card" css="my-card-menu" />
</div>
</template>
For filtering items per card, gating the menu, and opening it from code, see the Card Menu guide.
Adding, updating, moving, deleting cards
All card mutations go through actions dispatched via api.exec(). The widget doesn't modify the source cards array directly - the internal store handles immutable updates and triggers re-rendering.
<script setup>
import { ref } from "vue";
import { Kanban } from "@svar-ui/vue-kanban";
const api = ref(null);
</script>
<template>
<Kanban ref="api" :cards="cards" :columns="columns" />
<button :onclick="() => api.exec('add-card', {
card: { label: 'New task', column: 'todo' },
})">
Add
</button>
</template>
Key actions:
add-card- creates a card. Passedit: trueto open the editor on it immediately. Usebefore(a card id, ornullto append) orafterto control insertion position. When you pass both,beforewins.update-card- patches a card by id:api.exec("update-card", { id: 1, card: { progress: 0.5 } }).move-card- moves a card to a different column or reorders within the same column:api.exec("move-card", { id: 1, column: "done", before: null }). Settingbefore: nullplaces the card at the end. On boards with swimlanes (PRO), passswimlaneto move the card to another lane.duplicate-card- clones a card with optional overrides:api.exec("duplicate-card", { id: 1, card: { label: "Copy" } }).delete-card- removes a card:api.exec("delete-card", { id: 1 }).
To react to mutations, use event handler props (onaddcard, onupdatecard, onmovecard, etc.) or the api.on() / api.intercept() methods. Interceptors can cancel an action by returning false.
Selection and editor opening
Clicking a card dispatches select-card, which populates the store's editorData field. If an Editor component is mounted, it opens automatically for the selected card.
<script setup>
import { ref } from "vue";
import { Kanban, Editor } from "@svar-ui/vue-kanban";
const api = ref(null);
</script>
<template>
<Kanban ref="api" :cards="cards" :columns="columns" />
<Editor v-if="api" :api="api" />
</template>
Open or close the editor from code:
// Open editor for card 5
api.exec("select-card", { id: 5 });
// Close the editor
api.exec("select-card", { id: null });
Alternatively, pass a cardPopup component to replace the editor with a popup that appears on click:
<Kanban :cards="cards" :columns="columns" :cardPopup="MyPopup" />
The popup component receives { card, close } as props.
Performance
For boards with hundreds or thousands of cards, enable virtualization through the render prop to keep scroll performance smooth:
<Kanban
:cards="cards"
:columns="columns"
:render="{
virtualizeCards: true,
estimatedCardHeight: 96,
cardOverscan: 5,
}"
/>
This renders only the cards visible in each column's scroll viewport, plus a configurable overscan buffer. For boards with many columns, add virtualizeColumns: true as well.