Configuration
You can configure the Kanban appearance and functionality with the following properties:
cardShape— set up card appearance and built-in fieldseditorShape— define editor fieldseditor— control editor visibility, autosave, and placementrenderType,scrollType— adjust card rendering and board scrollinghistory— manage history of card operationscardTemplate— customize card appearance (see the Customization section)locale— apply a locale (see the Localization section)cards,columns,rows,links— load data for cards, columns, rows, and links (see the Working with data section)
Cards
The Kanban board consists of cards distributed into columns and rows. Use the cardShape property to configure card appearance and built-in fields:
label: boolean | { show }— card label, edited with thetexttypedescription: boolean | { show }— card description, edited with thetextareatypeprogress: boolean | { show }— card progress, edited with theprogresstypestart_date: boolean | { show, format }— card start date, edited with thedatetypeend_date: boolean | { show, format }— card end date, edited with thedatetypemenu: boolean | { show, items }— card context menuattached: boolean | { show }— card attachment, edited with thefilestypecolor: boolean | { show, values }— top color line of the card, edited with thecolortypecover: boolean | { show }— card preview imagecomments: boolean | { show }— card commentsconfirmDeletion: boolean | { show }— confirmation dialog for card deletionvotes: boolean | { show, clickable }— card votesusers: boolean | { show, values, maxCount }— users assigned to the card, edited with thecombo,select, ormultiselecttypespriority: boolean | { show, values }— card priority, edited with thecomboorselecttypecss: (card) => string— function that returns a CSS class applied to a card conditionallyheaderFields: [{ key, label, css }]— custom card fields
When you activate a field in cardShape, the editor displays the matching control automatically. Configure each control through the editorShape property — see Editor for the available types.
The following code snippet configures cards with custom users, priorities, and a custom header field:
const users = [ // users data
{ id: 1, label: "John Smith", avatar: "../assets/user.jpg" },
{ id: 2, label: "Aaron Short" }
];
const cardPriority = [ // card priority data
{ id: 1, color: "#FF5252", label: "high" },
{ id: 2, color: "#FFC975", label: "medium" },
{ id: 3, color: "#0AB169", label: "low" }
];
const cardShape = { // cards settings
label: true,
description: true,
progress: true,
start_date: true,
end_date: true,
menu: true,
attached: true,
priority: {
show: true,
values: cardPriority
},
users: {
show: true,
values: users
},
headerFields: [
{
key: "sprint",
label: "Custom field",
css: "custom_css_class"
}
]
};
new kanban.Kanban("#root", {
// cards data
columns,
cards,
// cards settings
cardShape
});
If you do not specify card settings through the cardShape property, the widget falls back to defaultCardShape.
Editor
The Kanban editor contains fields for managing card data. Use the editorShape property to configure editor fields. The following field types are available:
combo,select,multiselect— dropdown optionscolor— color pickertext,textarea— text inputsprogress— progress sliderfiles— file uploaderdate,dateRange— single date or date rangecomments— card commentslinks— card links
Display the editor as a sidebar or modal window with the editor.placement property.
Combo, select, and multiselect types
The following code snippet configures a dropdown for picking a card priority:
new kanban.Kanban("#root", {
editorShape: [
{
type: "combo", // or "select" and "multiselect"
key: "priority", // use the "priority" key in the "cardShape" property
label: "Priority",
values: [
{ id: 1, label: "high" },
{ id: 2, label: "medium" },
{ id: 3, label: "low" }
]
},
// settings for other fields
]
});
For multiselect and combo fields, set a path to the preview image through the avatar property:
editorShape: [
{
type: "multiselect", // or "combo"
key: "users", // use the "users" key in the "cardShape" property
label: "Users",
values: [
{
id: 1, label: "Alan",
avatar: "preview_image_path_1.png"
},
{
id: 2, label: "John",
avatar: "preview_image_path_2.png"
}
]
},
// settings for other fields
]
Color type
The following code snippet configures the editor field for picking a card color:
new kanban.Kanban("#root", {
editorShape: [
{
type: "color",
key: "color", // use the "color" key in the "cardShape" property
label: "Card color",
values: ["#65D3B3", "#FFC975", "#58C3FE"],
config: {
clear: true,
placeholder: "Select color"
}
},
// settings for other fields
]
});
Text and textarea types
The following code snippet configures the editor field for entering a card label:
new kanban.Kanban("#root", {
editorShape: [
{
type: "text", // or "textarea"
key: "label",
label: "Label",
config: {
placeholder: "Type your tips here",
readonly: false,
focus: true,
disabled: false,
inputStyle: "height: 50px;"
}
},
// settings for other fields
]
});
Progress type
The following code snippet configures the editor field for setting card progress:
new kanban.Kanban("#root", {
editorShape: [
{
type: "progress",
key: "progress", // use the "progress" key in the "cardShape" property
label: "Progress",
config: {
min: 10,
max: 90,
step: 5
}
},
// settings for other fields
]
});
Files type
Set the uploadURL parameter to a string for a basic upload, or to a function for a custom request.
Configure upload URL as string
The following code snippet uses a string URL for the file uploader:
const url = "https://docs.dhtmlx.com/kanban-backend";
new kanban.Kanban("#root", {
editorShape: [
{
type: "files",
key: "attached", // use the "attached" key in the "cardShape" property
label: "Attachment",
uploadURL: url + "/uploads", // set URL as string
config: {
accept: "image/*", // "video/*", "audio/*"
disabled: false,
multiple: true,
folder: false
}
},
// settings for other fields
]
});
Configure upload URL as function
Pass a function to uploadURL to add custom headers, tokens, or response handling. The following code snippet sends each file with a bearer token:
const url = "https://docs.dhtmlx.com/kanban-backend";
new kanban.Kanban("#root", {
editorShape: [
...defaultEditorShape,
{
key: "attached",
type: "files",
label: "Files",
uploadURL: rec => {
const formData = new FormData();
formData.append("upload", rec.file);
const config = {
method: "POST",
body: formData,
headers: {
'Authorization': 'Bearer ' + token // token or other headers here
}
};
return fetch(url + "/uploads", config) // URL here
.then(res => res.json())
.then(
data => {
return { id: rec.id, ...data };
},
() => ({ id: rec.id, status: "error" })
)
.catch();
}
}
]
});
Date and dateRange types
The following code snippet configures the editor field for a single date:
new kanban.Kanban("#root", {
editorShape: [
{
type: "date",
key: "start_date",
label: "Start date",
format: "%d/%m/%y"
},
// settings for other fields
]
});
The following code snippet configures the editor field for a start/end date range:
new kanban.Kanban("#root", {
editorShape: [
{
type: "dateRange",
key: {
start: "start_date",
end: "end_date"
},
label: "Date Range",
format: "%d/%m/%y"
},
// settings for other fields
]
});
Comments type
The following code snippet configures the comments field of the editor:
new kanban.Kanban("#root", {
editorShape: [
{
type: "comments",
key: "comments",
label: "Comments",
config: {
dateFormat: "%M %d",
placement: "page", // or "editor"
html: true,
confirmDeletion: true
}
},
// settings for other fields
]
});
Links type
The following code snippet configures the links field of the editor:
new kanban.Kanban("#root", {
editorShape: [
{
type: "links",
key: "links",
label: "Links",
config: {
confirmDeletion: true
}
},
// settings for other fields
]
});
Bind editor fields to card fields
Each editor field links to a card field through a shared key. Set the same key value in the editorShape entry and in the cardShape property. For built-in card fields, set the key to true. For custom fields, list the key in the headerFields array. The same key supplies initial card data.
The following code snippet binds the label and note editor fields to the matching card fields:
// editor settings
const editorShape = [
{
type: "text",
key: "label",
label: "Label",
config: {
placeholder: "Enter new label here"
}
},
{
type: "textarea",
key: "note",
label: "Note",
config: {
placeholder: "Enter usefull note here"
}
}
];
// cards settings
const cardShape = {
label: true, // built-in field key
headerFields: [
{
key: "note", // custom field key
label: "Note"
}
]
};
// cards data
const cards = [
{
label: "Volvo",
note: "It is the swedish car",
column: "backlog"
},
{
label: "Audi",
note: "It is the german car",
column: "backlog"
}
];
// create Kanban
new kanban.Kanban("#root", {
editorShape,
cardShape,
cards,
columns
// other configuration parameters
});
If you do not specify editor settings through the editorShape property, the widget falls back to defaultEditorShape. The default controls and inputs appear in the editor only after you activate the corresponding card fields through the cardShape property.
Configure editor behavior
The editor property controls editor visibility, autosave, and placement:
editor.show— enable or disable the editoreditor.placement— display the editor as a"sidebar"or"modal"windoweditor.autoSave— enable or disable autosave modeeditor.debounce— delay before autosaving (applies only withautoSave: true)
The following code snippet enables autosave with a 2-second delay:
// create Kanban
new kanban.Kanban("#root", {
columns,
cards,
editorShape,
editor: {
autoSave: true,
debounce: 2000
}
// other parameters
});
Rendering and scrolling
The Kanban widget renders all cards and scrolls the entire board by default. For boards with many cards, switch to lazy rendering or per-column scrolling:
renderType— set to"lazy"to render only the cards visible on the boardscrollType— set to"column"to scroll each column independently
The following code snippet enables lazy rendering and per-column scrolling:
new kanban.Kanban("#root", {
columns,
cards,
rows,
renderType: "lazy",
scrollType: "column",
cardHeight: 150
});
When you combine renderType: "lazy" with any scrollType, set a static height for cards through the cardHeight property. Without cardHeight, lazy rendering does not display cards correctly.
If cardHeight is omitted with renderType: "lazy" and scrollType: "column", the widget falls back to an experimental approximation of card heights based on the visible fields in cardShape. For boards that use a custom cardTemplate, the widget cannot predict the rendered height — supply a custom getCardHeight(cardShape, card, cardWidth) function that returns the estimated card height.
History of changes
Kanban tracks card operations and exposes undo and redo controls on the Toolbar. Use the history property to disable this behavior.
The following code snippet disables history tracking:
new kanban.Kanban("#root", {
columns,
cards,
history: false
});
To skip individual operations from history, pass the $meta parameter to methods or events.
Toolbar
The Kanban Toolbar provides a searchbar, sort controls, and controls for adding columns and rows. Initialize the Toolbar in a separate container with the kanban.Toolbar() constructor.
The following code snippet creates a Toolbar bound to the Kanban instance:
// create Kanban
const board = new kanban.Kanban("#root", {
// data
columns,
cards,
rows,
// card settings
cardShape,
// editor settings
editorShape
});
new kanban.Toolbar("#toolbar", { api: board.api });
Use the items property to show, hide, or customize Toolbar controls. The following code snippet sets a custom searchbar, undo and redo controls, a custom sort, and column and row controls:
// create Kanban
const board = new kanban.Kanban("#root", {...});
new kanban.Toolbar("#toolbar", {
api: board.api,
items: [
{ // custom search bar
type: "search",
options: [
{
id: "label",
label: "By label"
},
{
id: "start_date",
label: "By date",
searchRule: (card, value, by) => {
const date = card[by];
return date?.toString().includes(value);
}
}
],
resultTemplate: kanban.template(({ result }) => {
return `<div className="list-item">
<div className="list-item-text">${result.label}</div>
${result.description ? `<div className="list-item-text item-description">${result.description}</div>` : ""}
</div>`
})
},
"spacer", // empty space
"undo", // undo card operations in the history
"redo", // redo card operations in the history
{ // custom sort control
type: "sort",
options: [
{
text: "Sort by label",
by: "label",
dir: "asc"
},
{
text: "Sort by description",
by: "description",
dir: "desc"
}
]
},
"addColumn", // control for adding new columns
"addRow", // control for adding new rows
// custom elements
]
});
Remove a control from the items array to hide that control.
Example
The following snippet configures the cards, editor, and Toolbar of Kanban: