Skip to main content

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,
}"
/>

Card showing built-in sections: priority badge, description, progress bar, deadline, tags, and user avatars

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>

Card with three-dot menu button open showing Edit, Duplicate, and Delete options

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. Pass edit: true to open the editor on it immediately. Use before (a card id, or null to append) or after to control insertion position. When you pass both, before wins.
  • 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 }). Setting before: null places the card at the end. On boards with swimlanes (PRO), pass swimlane to 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.