Skip to main content

Menus

You can give users card and column actions, such as edit, duplicate, delete, add card, or anything custom, on ⋯ buttons and on right click. You don't need to build the menu yourself.

The board doesn't mount a menu. It renders only the markup that a menu needs: ids on cards and column headers, and optional ⋯ buttons. Four wrapper components turn this markup into menus:

WrapperOpens onDefault items
CardActionMenuclick on a card ⋯ buttongetMenuOptions()
CardContextMenuright click anywhere on a cardgetMenuOptions()
ColumnActionMenuclick on a column ⋯ buttongetColumnMenuOptions()
ColumnContextMenuright click anywhere on a column headergetColumnMenuOptions()

Each wrapper goes around <Kanban>, either directly or through other wrappers. Each wrapper needs the kanban api, which you get from ref or init. Until api is set, the wrapper doesn't open.

All four wrappers take the same props:

  • api - the kanban instance. The wrapper uses it to find the target card or column and to run the built-in actions.
  • options - an array of items, or a function (ctx) => items. The wrapper calls the function each time the menu opens.
  • resolver - a gate that runs after the wrapper finds the target. If it returns a falsy value, the menu stays closed.
  • filter - a per-item filter for the target.
  • onclick - called when the user selects an item. ev.action is the item and ev.context is the target. Closing the menu without a selection doesn't call it.
  • at - placement of the menu. The default is "point", which opens the menu at the pointer.
  • css - an extra CSS class for the menu.

Each wrapper also has a show(ev, obj?) method that opens the menu from your own code.

The targets of the four wrappers never overlap, so you can nest the wrappers in any order. When one menu opens, the outer wrappers ignore that event.

<script setup>
import {
Kanban,
Editor,
CardActionMenu,
CardContextMenu,
ColumnActionMenu,
ColumnContextMenu,
} from "@svar-ui/vue-kanban";
import { ref } from "vue";

const api = ref();
</script>

<template>
<CardContextMenu :api="api">
<CardActionMenu :api="api">
<ColumnContextMenu :api="api">
<ColumnActionMenu :api="api">
<Kanban ref="api" :cards="cards" :columns="columns" :card="{ menu: true }" />
</ColumnActionMenu>
</ColumnContextMenu>
</CardActionMenu>
</CardContextMenu>
<Editor v-if="api" :api="api" />
</template>

The wrappers are outside <Kanban>, so they don't get the board's locale. To translate menu labels, put a <Locale> around both the wrappers and the board. Without it, the labels are in English. For more information, see Localization.

Card menus​

A card menu can open in two ways:

  • ⋯ button. Set menu: true in the card prop to show the button on each card. Then wrap the board in CardActionMenu. The button only adds markup. Without an outer CardActionMenu, the button does nothing. A click on the button doesn't select the card.
  • Right click. Wrap the board in CardContextMenu. A right click anywhere on a card opens the menu. This doesn't need card.menu.

To use both, nest the wrappers and give them the same options and onclick:

<script setup>
import {
Kanban,
Editor,
CardActionMenu,
CardContextMenu,
} from "@svar-ui/vue-kanban";
import { ref } from "vue";

const api = ref();
</script>

<template>
<CardContextMenu :api="api">
<CardActionMenu :api="api">
<Kanban ref="api" :cards="cards" :columns="columns" :card="{ menu: true }" />
</CardActionMenu>
</CardContextMenu>
<Editor v-if="api" :api="api" />
</template>

Board with right-click context menu open on a card showing Edit, Duplicate, and Delete options

The Editor is optional, but the built-in "Edit card" item needs it to open the editor for the card.

For card menus, the target (ctx) is the card object.

Card menu button in a custom template​

If you use cardContent, your template replaces the built-in ⋯ button too. To keep the button, render CardMenuButton in the template. It is the same button that the built-in card uses, with the theme styling and a localized label. Keep CardActionMenu around the board as usual:

<!-- 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>{{ card.label }}</strong>
<CardMenuButton v-if="cardShape.menu" :card="card" css="my-card-menu" />
</div>
</template>

CardMenuButton takes card (required) and css (extra classes). The template decides when to show it. Don't build the button attributes by hand.

Column menus​

A column menu also opens in two ways:

  • ⋯ button. Set menu: true on a column in columns. The button appears in the column header. Then wrap the board in ColumnActionMenu. The button is off by default and you enable it for each column separately.
  • Right click. Wrap the board in ColumnContextMenu. A right click on any column header opens the menu, also on a collapsed column.
<script setup>
import {
Kanban,
ColumnActionMenu,
ColumnContextMenu,
} from "@svar-ui/vue-kanban";
import { ref } from "vue";

const api = ref();

const columns = [
{ id: "backlog", label: "Backlog", menu: true },
{ id: "inprogress", label: "In progress", menu: true },
{ id: "done", label: "Done", menu: true },
];
</script>

<template>
<ColumnContextMenu :api="api">
<ColumnActionMenu :api="api">
<Kanban ref="api" :cards="cards" :columns="columns" />
</ColumnActionMenu>
</ColumnContextMenu>
</template>

Column header menu open from the dots button with the default Add card item

For column menus, the target is a ColumnMenuContext object:

type ColumnMenuContext = {
column: ColumnView; // the projected column
cards: KanbanCard[]; // the cards under the header
swimlane?: SwimlaneView; // stack layout only
};

In the stack layout, cards contains the cards of one lane only.

The ⋯ button adds a small slot to the column header. If the header is too narrow, make the column wider or turn off other header features.

Default options​

If you don't set options, the card wrappers show the items from getMenuOptions() and the column wrappers show the items from getColumnMenuOptions():

ItemItem idWhat it does
Edit cardedit-cardOpens the editor on the card (select-card)
Duplicate cardduplicate-cardDuplicates the card (duplicate-card)
Delete carddelete-cardDeletes the card (delete-card)
Add cardadd-cardAdds a card to the column and opens its editor if mounted

With the default column items, the wrappers hide "Add card" on columns that have addCard: false.

Some item ids are built in. When the user selects an item with a built-in id, the wrapper runs its action first and then calls onclick:

  • Card ids: edit-card, duplicate-card, delete-card.
  • Column ids: add-card and collapse-column. collapse-column isn't in the default items, but you can add it. It collapses or expands the column through update-column.

Items with other ids only reach onclick.

Custom items​

To add items, spread the default options and add your entries with a custom id, text, and icon. Handle the custom ids in onclick:

<script setup>
import {
Kanban,
Editor,
CardActionMenu,
CardContextMenu,
getMenuOptions,
} from "@svar-ui/vue-kanban";
import { ref } from "vue";

const api = ref();

const options = [
...getMenuOptions(),
{ id: "archive-card", text: "Archive", icon: "wxi-empty" },
];

function onclick({ action, context }) {
if (action.id === "archive-card") {
api.value.exec("update-card", {
id: context.id,
card: { archived: true },
});
}
}
</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>
<Editor v-if="api" :api="api" />
</template>

Items that depend on the target​

options can be a function. The wrapper calls it each time the menu opens, with the target as the argument. The items then match the current state of the card or column. If the function returns an empty list or a falsy value, the menu stays closed.

When you set options, the wrapper uses your items as they are. For example, it doesn't hide "Add card" on addCard: false columns. Check the target yourself:

<script setup>
import {
Kanban,
ColumnActionMenu,
ColumnContextMenu,
getColumnMenuOptions,
} from "@svar-ui/vue-kanban";
import { ref } from "vue";

const api = ref();
const columns = [
{ id: "todo", label: "To do", menu: true },
{ id: "done", label: "Done", menu: true, addCard: false },
];

function options(ctx) {
const items = getColumnMenuOptions().filter(
o => o.id !== "add-card" || ctx.column.addCard
);
if (ctx.cards.length) {
items.push(
{ comp: "separator" },
{
id: "clear-column",
text: `Delete ${ctx.cards.length} card(s)`,
icon: "wxi-delete",
}
);
}
return items;
}

function onclick({ action, context }) {
if (action.id === "clear-column") {
context.cards.forEach(c => api.value.exec("delete-card", { id: c.id }));
}
}
</script>

<template>
<ColumnContextMenu :api="api" :options="options" :onclick="onclick">
<ColumnActionMenu :api="api" :options="options" :onclick="onclick">
<Kanban ref="api" :cards="cards" :columns="columns" />
</ColumnActionMenu>
</ColumnContextMenu>
</template>

The "Delete card(s)" item shows only when the column has cards, and its label shows how many cards it will delete.

Gating and filtering​

Use resolver to block the menu for some targets, and filter to hide individual items.

resolver gets the target and the mouse event. If it returns a falsy value, the menu stays closed. filter gets each item and the target. Return false to hide the item:

<template>
<CardContextMenu
:api="api"
:resolver="card => !card.readOnly"
:filter="(item, card) => !(card.locked && item.id === 'delete-card')"
>
<Kanban ref="api" :cards="cards" :columns="columns" />
</CardContextMenu>
</template>

In this example, read-only cards show no menu. Locked cards show the menu without "Delete card".

The menus don't check readonly on <Kanban>. On a readonly board you decide what users can do. You can leave out the wrappers, block them with resolver, or give them only items that don't change data:

<template>
<CardContextMenu :api="api" :resolver="() => !readonly">
<Kanban ref="api" :cards="cards" :columns="columns" :readonly="readonly" />
</CardContextMenu>
</template>

For the card ⋯ button, set card.menu from the readonly flag:

<template>
<CardActionMenu :api="api">
<Kanban
ref="api"
:cards="cards"
:columns="columns"
:readonly="readonly"
:card="{ menu: !readonly }"
/>
</CardActionMenu>
</template>

This hides the button only. Use resolver to gate an attached CardContextMenu separately.

Migrating from ContextMenu​

Earlier versions mounted the card menu inside <Kanban> and took the menu settings through card.menu = { options, filter, onclick }. That object form is removed. card.menu is now a boolean that only controls visibility of the ⋯ button.

To migrate:

  1. Replace card.menu = { ... } with card.menu = true.
  2. Wrap the board in CardActionMenu and move options, filter, and onclick to it.
  3. Replace <ContextMenu> with <CardContextMenu>. The props are the same.
<!-- before -->
<template>
<ContextMenu :api="api" :options="options" :onclick="onclick">
<Kanban
ref="api"
:cards="cards"
:columns="columns"
:card="{ menu: { options, onclick } }"
/>
</ContextMenu>
</template>

<!-- after -->
<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>

ContextMenu is still exported as a deprecated alias of CardContextMenu, so old code keeps working for right click. Switch to CardContextMenu when you can.

In onclick, use ev.context to get the target card.