Dojo NG is being built in the open, one section at a time — follow along on Heptapod.

Playground Docs Components Migrate Blog Community Source GitHub
★ GitHub ★ Heptapod Get started

API REFERENCE · DATA DISPLAY

<dj-board>

A Kanban board over plain records.

Cards are the records in data. Lanes are the values of one field, named by group-by. Within a lane, cards keep their order in data.

Try it in the playground

@dojo-ng/board · v0.1.1

npm install @dojo-ng/board

import "@dojo-ng/board";

Moving cards

  • The board is controlled: it never changes data. Every move emits dj-card-move, and your app applies it and assigns the new array. The exported applyCardMove does that in one line.
  • When the new data arrives, focus follows the moved card and the move is announced to assistive technology.
  • Cards move with the move menu or the keyboard. Set draggable to also allow pointer and touch drag between lanes. Drag is an extra: the menu and the keyboard stay available, so dragging is never the only way to move a card.

Lanes and cards

  • Set lanes explicitly when you can. It fixes the lane order, gives each lane a label, and shows empty lanes. Without it, lanes come from the values found in data.
  • renderCard supplies the card content. The board draws it inside its own accessible card shell, so a custom card cannot break accessibility. Without renderCard, each card is a dj-card showing the card-title field.
  • Work-in-progress limits are advisory: the lane shows a count such as 3/5 and gets a style hook when it is over the limit, but moves are never blocked.

Keyboard

The board is one tab stop.

  • The arrow keys move between cards and lanes; Home and End move within a lane.
  • Enter activates the card.
  • Space or M opens the move menu.
  • Ctrl+arrow (Cmd+arrow on a Mac) moves the card itself.

Properties

PropertyAttributeTypeDefault
dataThe cards (plain records). Lane order = order of appearance. Set in JavaScript. Property only Card[] []
lanesLane definitions in display order. Empty → lanes derive from distinct group-by values in data order (explicit lanes recommended). Set in JavaScript. Property only BoardLane[] []
groupByField that assigns a card to a lane (compared as a string). group-by string "status"
cardKeyField giving a card's stable identity (must be unique across data). card-key string "id"
cardTitleField used for the default card content, the card's accessible name, and announcements. card-title string "title"
labelAccessible name for the board. label string None
renderCardCustom card content, rendered inside the component-owned shell. Set in JavaScript. Property only (card: Card) => TemplateResult None
draggableProgressive enhancement: enable pointer drag of cards between lanes. The move menu and keyboard shortcuts remain the accessibility contract (WCAG 2.5.7); drag never replaces them. draggable reflected boolean false

Events

EventDescription
dj-card-movedetail { card, key, from, to, fromIndex, toIndex }; the board never applies it itself
dj-card-clickdetail { card, key }

Slots

SlotDescription
nonecards come from data

CSS parts

Style these with dj-board::part(name).

boardlanelane-overlane-headerlane-titlelane-countlane-bodycardmove-buttonlane${over?

Methods

MethodDescription
effectiveLanes(): BoardLane[]The lanes to display: the lanes property, or distinct group-by values in data order.

Types

The types that the properties above use, as they are declared in the source.

Card

export type Card = Record<string, unknown>;

BoardLane

export interface BoardLane {
  value: string;
  label?: string;
  limit?: number;
}