Skip to main content

Configuration

The Kanban board can be customized in both looks and features using its API. There are plenty of parameters to help set things up the way you want:

Cards​

On a Kanban board, cards are organized into columns and rows. The cardShape property lets you decide what fields appear on each card. Some common fields you can toggle on or off include:

  • Card label, using label: boolean

  • Card description, using description: boolean

    tip

    The label and description fields can be edited right in the Kanban editor. If you turn these on, matching inputs will show up in the editor automatically. To fine-tune these inputs, you can use the text and textarea field types.

  • Card progress, with progress: boolean

    tip

    The progress field is controlled through the Kanban editor as well. If enabled, a matching control shows up in the editor. To customize it, use the progress type.

  • Start date, using start_date: boolean

  • End date, using end_date: boolean

    tip

    Both start date and end date fields are managed through the editor. If you enable them, controls appear automatically. To configure them, use the date type.

  • Card context menu, with menu: boolean

  • Card attachment, using attached: boolean

    tip

    You can attach files to a card using the editor’s field. To set this up, use the files type.

  • Card color, with color: boolean

    tip

    The color line at the top of a card can be set in the editor. If color is enabled, a color picker appears in the editor. To adjust this, use the color type.

  • Card cover image, with cover: boolean

  • Card comments, using comments: boolean

  • Confirmation dialog for card deletion, with confirmDeletion: boolean

  • Card voting, using votes: boolean | { show: boolean, clicable: true }

  • Card assignment (users), with users: boolean | { show: boolean, values: object, maxCount: number | false }

    tip

    Assigning users to a card is done through the editor. To assign one user, use the combo or select types. For multiple users, go with multiselect.

  • Card priority, with priority: boolean | { show: boolean, values: object }

    tip

    Priorities can be managed through the editor too. With priority enabled, a control appears in the editor. Only combo or select types work for this.

  • Custom fields, using 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 set up card fields using cardShape, Kanban will use its defaultCardShape settings!

Editor​

info

The Editor can show up as a sidebar or a modal window. Use the editor.placement property to pick which one!

The Kanban Editor is where card details are managed. To set up which fields show up in the editor, use the editorShape property. Here are the editor field types you can use:

Combo, Select and Multiselect types​

Editor fields for combo, select, and multiselect 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 "multiselect" and "combo" fields, you can also add a preview image using 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 add a color picker field in the editor, set it up like this:

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​

To add text or textarea fields to the editor, use this setup:

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​

A progress field in the editor can be configured 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​

To let users attach files, set up a files field in one of 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​

To add a date field to the editor:

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

For a dateRange field, use:

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​

To enable comments in 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 of other fields
    ]
});

To let users add links in the editor:

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 property (like key: "editor_field_key"). For built-in fields, that key should be set to true in cardShape. For custom fields, add it to the headerFields array. You can also use this key to set initial data for a field.

// 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 you don’t set up editor fields with editorShape, Kanban uses its defaultEditorShape settings. In this case, default controls and inputs only show up in the editor after you enable the matching card fields using cardShape.

Configuring the editor​

The editor property can be used to tweak how the editor works:

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

Toolbar​

The Kanban Toolbar includes a search bar for finding cards, as well as controls for sorting cards and adding new columns or rows. To show 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 (showing, hiding, or customizing them) are managed through 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

To hide Toolbar controls, just remove their strings from the items array.

Example​

Here’s a snippet that shows how to set up Cards, the Editor, and the Toolbar in Kanban: