Skip to main content

Configuration

The Kanban widget can be customized in both look and features using its API. There are a variety of options you can tweak, such as:

Cards​

In Kanban, cards are organized into columns and rows. You can control how cards look and what info they display using the cardShape property. There are several built-in fields you can choose to show or hide, including:

  • Card label using the label: boolean option
  • Card description using the description: boolean option
tip

Both the label and description fields can be edited through the Kanban editor. Turning them on will make the corresponding inputs visible automatically. These inputs are set up through the text and textarea types.

  • Progress bar using progress: boolean
tip

The progress field can also be managed from the Kanban editor. If enabled, its control will show up automatically. This is configured using the progress type.

  • Start date with start_date: boolean
  • End date with end_date: boolean
tip

Both start date and end date are managed with controls in the Kanban editor. If these are active, their controls will appear automatically. Use the date type to set them up.

  • Card context menu using menu: boolean
  • Attachments with attached: boolean
tip

Cards can have files attached through the Kanban editor. This is handled by the files type.

  • Card color using color: boolean
tip

The top color line on a card is managed with a control in the Kanban editor. When color is enabled, a color picker will automatically appear. This uses the color type.

  • Card cover image (preview) via cover: boolean
  • Comments on cards using comments: boolean
  • Confirmation dialog for deleting cards with confirmDeletion: boolean
  • Votes on cards using votes: boolean | { show: boolean, clicable: true }
  • User assignments using users: boolean | { show: boolean, values: object, maxCount: number | false }
tip

Assigning users to cards is done through a control in the Kanban editor. To let users pick just one assignee, use the combo or select types. For multiple assignees, use the multiselect type.

  • Priority field using priority: boolean | { show: boolean, values: object }
tip

Card priority can be set with a control in the Kanban editor. Turning on priority makes the control show up automatically. Only the combo or select types are used here.

  • Custom fields can be added in headerFields: [ { key: string, label: string, css: string } ]
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
});
note

If you don't define your own card settings through cardShape, Kanban will use the defaultCardShape settings!

Editor​

info

You can have the Editor show up as a sidebar or modal window by setting the editor.placement property!

The Kanban Editor is where card details get managed. You can set up which fields show in the editor by using the editorShape property. The available field types include:

Combo, Select and Multiselect types​

Editor fields of these types are set up like this:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "combo", // or "select" and "multiselect"
            key: "priority", // the "priority" key is used when configuring the "cardShape" property
            label: "Priority",
            values: [
                { id: 1, label: "high" },
                { id: 2, label: "medium" },
                { id: 3, label: "low" }
            ]
        },
        // settings of other fields
    ]
});
info

For editor fields of "multiselect" and "combo" you can include a preview image by setting the avatar property:

editorShape: [
    {
        type: "multiselect", // or "combo"
        key: "users", // the "users" key is used when configuring 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 of other fields
]

Kanban. Limiting assignments to one user only

Color type​

To set up a color picker in the editor, use:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "color",
            key: "color", // the "color" key is used when configuring the "cardShape" property
            label: "Card color",
            values: ["#65D3B3", "#FFC975", "#58C3FE"],
            config: {
                clear: true,
                placeholder: "Select color"
            }
        },
        // settings of other fields
    ]
});

Text and Textarea types​

Add text fields or multi-line inputs like this:

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 of other fields
    ]
});

Progress type​

Progress bars in the editor are set like this:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "progress",
            key: "progress", // the "progress" key is used when configuring the "cardShape" property
            label: "Progress",
            config: {
                min: 10,
                max: 90,
                step: 5
            }
        },
        // settings of other fields
    ]
});

Files type​

Set up file uploads in the editor in two ways:

Configuring Upload Url as String​

const url = "https://docs.dhtmlx.com/kanban-backend";
new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "files",
            key: "attached", // the "attached" key is used when configuring the "cardShape" property
            label: "Attachment",
            uploadURL: url + "/uploads", // specify url as string
            config: {
                accept: "image/*", // "video/*", "audio/*"
                disabled: false,
                multiple: true,
                folder: false
            }
        },
        // settings of other fields
    ]
});

Configuring Upload Url as Function​

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 => {
                            rec.id = data.id;
                            return data;
                        },
                        () => ({ id: rec.id, status: "error" })
                    )
                    .catch();
            }
        }
    ]
});

Date and DateRange types​

Add date pickers or date ranges like this:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "date",
            key: "start_date",
            label: "Start date",
            format: "%d/%m/%y"
        },
        // settings of other fields
    ]
});

For a date range:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "dateRange",
            key: {
                start: "start_date",
                end: "end_date"
            },
            label: "Date Range",
            format: "%d/%m/%y"
        },
        // settings of other fields
    ]
});

Comments type​

Include a comments field in the editor like this:

new kanban.Kanban("#root", {
    editorShape: [
       {
            type: "comments",
            key: "comments",
            label: "Comments",
            config: {
                dateFormat: "%M %d",
                placement: "page", // or "editor"
                html: true,
                confirmDeletion: true
            }
        },
        // settings of other fields
    ]
});

To allow adding links in the editor, use:

new kanban.Kanban("#root", {
    editorShape: [
        {
            type: "links",
            key: "links",
            label: "Links",
            config: {
                confirmDeletion: true
            }
        },
        // settings of other fields
    ]
});

Binding editor fields to card fields​

info

To connect an editor field to a card field, set the key in the editorShape object (key: "editor_field_key"). For built-in card fields, make sure this key is set to true in cardShape. For custom fields, add it to the headerFields array. You can also set the initial value for any field with this key.

// 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, // a key of built-in field
    headerFields: [
        {
            key: "note", // a key of custom field
            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
});
note

If no editor settings are defined via editorShape, the widget falls back to defaultEditorShape. The default inputs and controls will then only appear if you turn on the matching card fields in cardShape.

Configuring the editor​

You can tweak editor behavior using the editor property:

  • Turn autosave on or off with editor.autoSave
  • Set the autosave delay using editor.debounce (only works if autoSave: true is on)
// create Kanban
new kanban.Kanban("#root", {
    columns,
    cards,
    editorShape,
    editor: {
        autoSave: true,
        debounce: 2000
    }
    // other parameters
});

Toolbar​

The Kanban Toolbar comes with a search bar (for finding cards), controls for sorting, and buttons to add new columns or rows. To use the Toolbar, initialize it in a separate container using kanban.Toolbar().

// 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 });

Toolbar controls can be shown, hidden, or customized with the items property:

// 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(searchResult => {
                return `<div className="list-item">
                            <div className="list-item-text">${searchResult.result.label}</div>
                            ${searchResult.result.description ? `<div className="list-item-text item-description">${searchResult.result.description}</div>` : ""}
                        </div>`
            })
        },
        "spacer", // empty space
        "undo", // control to undo the card operations in the history
        "redo", // control to redo the 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
    ]
});
tip

If you want to hide some Toolbar controls, just remove their strings from the items array.

Example​

Here's a snippet showing how to set up Cards, Editor, and Toolbar for Kanban: