Kanban JAVASCRIPT UI Component API

Kanban Javascript API

Class

Kanban

Kanban

Kanban represents a kanban board that visually depicts work at various stages of a process using cards to represent tasks and columns to represent each stage of the process.

Selector

smart-kanban

Properties

AallowColumnReorderControls whether users can reorder columns in a table or grid. When set to true and used in combination with allowDrag enabled, this property lets users rearrange columns by dragging and dropping their headers. For example, a user can click and hold the header of the first column, then drag it to a new position over another column header and drop it, changing the column order visually and functionally. This enhances the user experience by allowing customizable column layouts.
AallowColumnEditControls whether column editing is permitted. When this property is set to true, users can dynamically edit the column's header label by double-clicking on it. This allows for in-place renaming of the column header directly within the user interface. If set to false, the column header label will remain static and cannot be modified by users.
AallowColumnRemoveControls whether users can remove columns from the table. When set to true, a "Remove Column" option will appear in the column actions menu, allowing users to dynamically delete columns. Note: The 'columnActions' property must also be enabled (set to true) for this feature to be available.
AallowColumnHideControls whether users can hide columns in the data table. When set to true, this property allows users to dynamically hide individual columns using the column actions menu. Note: To enable this feature, the 'columnActions' property must also be set to true.
AaddNewButtonControls whether the "Add Task" button is displayed at the top of each column. To hide the button for an individual column, set the addNewButton property to false within that column’s configuration object. If addNewButton is false, users will not see the "Add Task" button for that specific column.
AaddNewButtonDisplayModeSpecifies whether the add button appears in the column header, after the list of tasks within the column, or both. This controls the visibility and placement of the add button for creating new tasks in each column.
AaddNewColumnSpecifies whether a special column containing a button for adding new status columns to the Kanban board is shown. When enabled, this feature allows users to quickly create additional status columns directly within the Kanban interface. You can use this setting to display or hide the "Add Column" button column as needed.
AaddNewColumnWidthSpecifies the width of the dynamically added "Add New" column. This property is effective only when the 'columnWidth' property is also set. It allows you to control the exact width (in pixels or other valid CSS units) of the new column that appears when adding columns dynamically to the table or grid.
AallowDragEnables users to click and drag tasks within the interface, allowing them to easily reorder, move, or reorganize tasks by dragging and dropping them to the desired position.
AallowDropEnables users to remove or discard tasks from the list or workflow, either by dragging and dropping or through a designated action, facilitating task management and organization.
AallowDropPlaceholderEnables a visual placeholder to appear when dragging and dropping tasks. As you drag a task over another task, an empty space is dynamically created at the drop location, clearly indicating where the dragged task will be inserted. This improves usability by providing real-time visual feedback during task reordering.
AapplyColumnColorToTasksThis property controls the color styling of Kanban columns and their associated tasks. When set to true, and if a Kanban column has its color property defined, that color will not only visually highlight the column header but will also be applied to all tasks within that column, as well as to the background or accent color of the edit dialog for tasks in that column. This creates a consistent and visually cohesive color scheme throughout each column and its related UI elements.
AautoLoadStateControls whether the application automatically loads its state from the browser’s localStorage. This includes restoring information such as:- The list of tasks and their positions- The selected task and its state- Applied filters and sorting options- The state of collapsed columns- The values of the following task-related properties: - taskActions - taskComments - taskDue - taskPriority - taskProgress - taskTags - taskUserIconWhen enabled, all of these details will be reloaded from localStorage on page refresh or reopening the application, ensuring a consistent user experience. When disabled, this information will not be loaded automatically, and the state will not be restored.
AautoSaveStateControls whether the application's current state is automatically saved to the browser's localStorage. When enabled, the following information is persistently stored and restored across sessions: - Task data, including their current positions, selected status, and any applied filters or sorting.- The collapsed or expanded state of columns.- Values for the following properties: - taskActions (user actions related to tasks) - taskComments (comments attached to tasks) - taskDue (task due dates) - taskPriority (priority level of tasks) - taskProgress (progress tracking for tasks) - taskTags (tags associated with each task) - taskUserIcon (user avatars/icons linked to tasks)This ensures that user preferences and the state of the task interface are preserved, providing a seamless user experience even after closing or refreshing the browser. Disabling this feature will prevent any state information from being stored in localStorage, and all settings will be reset upon page reload.
AautoColumnHeightDynamically adjusts the height of each column based on the total height of its tasks, ensuring all content is fully visible. This property is effective only when 'columnColorEntireSurface' is set to true, allowing the background color to extend appropriately over the column’s entire surface.
CcollapsibleEnables the card content to be expanded or collapsed, providing users with the ability to show or hide additional information within the card. This enhances the user interface by reducing visual clutter and allowing for more compact content presentation.
CcolumnColorsDisplays a color indicator in the column header whenever the column's color property is defined. The header visually reflects the assigned color, making it easier to identify and distinguish columns based on their color settings.
CcolumnWidthDefines the width for each Kanban column. When this property is specified, all Kanban columns are rendered at the given width. If the total width of all columns exceeds the available space, a horizontal scrollbar will appear, allowing users to scroll and view all columns.
CcolumnColorEntireSurfaceRenders a customizable background within the Kanban column, allowing for enhanced visual separation and improved column identification. Supports various background options such as color, image, or pattern to match your application's design requirements.
CcolumnFooterRenders a column footer that displays a summary value, such as totals or averages, for the data in that column. This footer helps users quickly interpret aggregate information at the bottom of the column.
CcolumnsProvides detailed definitions and configuration options for each column’s properties, including attributes such as data type, default value, visibility, header label, and formatting options. Click for more details. Property object's options:
  • addNewButton:boolean - Sets or gets whether the column's button for adding tasks is visible. Works in conjunction with the Kanban property of the same name.
  • allowRemove:boolean - Sets or gets whether the column can be removed from the column menu.
  • collapsed:boolean - Sets or gets whether the column is collapsed.
  • collapsible:boolean - Sets or gets whether the column is collapsible. Works in conjunction with the Kanban property of the same name.
  • columns:{ addNewButton?: boolean, collapsed?: string, collapsible?: string, columns?: [], dataField?: string, label?: string, orientation?: string, selected?: string }[] - Sets or gets the column's sub-columns. Sub-columns has the same properties as top-level columns.
  • dataField:string - Sets or gets the column's data source bound field. Corresponds to the status field in the data source.
  • label:string - Sets or gets the text displayed in the column's header.
  • editable:boolean - Sets or gets whether a column is editable.
  • visible:boolean - Sets or gets whether a column is visible.
  • reorder:boolean - Sets or gets whether a column can be reordered.
  • orientation:string - Sets or gets whether the tasks in the column flow vertically or horizontally.
  • selected:boolean - Sets or gets whether the column is selected. Only applicable to sub-columns when hierarchy is 'tabs'.
  • headerTemplate:any - Determines whether a column header has a template. You can pass 'string', 'function' or HTMLTemplateElement as a value.
  • width:number | null - Sets the Kanban column width. When this property is set, the kanban column width is set and a horizontal scrollbar may appear.
CcolumnActionsControls whether the column actions icon is displayed, allowing users to access additional options or actions for each table column. When enabled, the icon becomes visible; when disabled, the icon is hidden from view.
CcolumnSummarySpecifies whether the number of tasks is shown in the headers of each column, allowing users to see the count of tasks directly within the column titles.
CcolumnHeaderTemplateSpecifies whether a custom template is applied to the column header. Accepts a value of type string (containing template markup), function (returning a template or markup), or an HTMLTemplateElement. Use this property to customize the appearance and content of the column header beyond the default rendering.
CcolumnEditModeSpecifies how column editing is initiated within the interface. - When set to ''header'', editing mode is activated by double-clicking directly on the column's header label. - When set to ''menu'', editing can only be started through the column's context or 'columnActions' menu. - When set to ''headerAndMenu'', both methods are available—users can begin editing either by double-clicking the header or by selecting the relevant option from the column menu.
CcurrentUserSets or retrieves the ID of the currently active user. This value must match the 'id' of a user object within the 'users' property or array. The privileges and access rights available are determined based on the current user's identity. If no current user is specified, the element's permissions default to those defined by its own properties, rather than user-specific settings.
DdisableDialogControls whether the default dialog for adding or removing tasks or comments is enabled or disabled. When set to true, the dialog will not appear, allowing for custom handling of these actions. When set to false, the standard dialog will be shown as usual. This property can be used to either retrieve the current setting (get) or define its behavior (set).
DdialogCustomizationFunctionSets or retrieves a customization function for the Kanban dialog component. This function allows you to modify the appearance and behavior of the dialog, or to replace it entirely with a custom implementation. When invoked, the Kanban component calls this function with five arguments:- 'dialog': The default dialog instance, typically a 'smart-window' object, which serves as the default modal dialog for tasks and comments.- 'taskOrComment': The data object representing either a Kanban task or a comment, depending on the context of the action.- 'editors': An object containing the input elements or editors used within the dialog for data entry or modification.- 'purpose': A string indicating the dialog’s intent, such as ''add'' for creating a new item or ''edit'' for modifying an existing one.- 'type': A string specifying the entity being processed, such as ''task'' for task-related dialogs or ''column'' for column-related dialogs.By providing a custom function, you can tailor the dialog’s UI, integrate additional logic, or substitute a completely different dialog component to meet your application's requirements.
DdialogRenderedSets or retrieves the callback function that is executed when the dialog is rendered. This function is invoked by the Kanban component and receives six arguments: dialog, editors, labels, tabs, layout, and taskOrComment.- 'dialog': The 'smart-window' instance representing the Kanban dialog.- 'taskOrComment': An object representing either the current Kanban task or a comment, depending on the context in which the dialog is opened.- 'editors, labels, tabs, layout': Each is a JSON object where keys specify the element type (e.g., 'description', 'priority', 'notes'), and the values are their corresponding HTML elements within the dialog.This function allows developers to customize the dialog content or behavior dynamically based on the element types and the associated data when the dialog is rendered.
DdataSourceSpecifies the origin or source of the data to be displayed and managed on the Kanban board, such as an API endpoint, database, or local data array. This setting dictates which dataset will populate the Kanban columns and cards. Click for more details. Property object's options:
  • id:string | number - The task's unique ID.
  • checklist:{ completed?: boolean, text?: string }[] - A list of sub-tasks.
  • color:string - A color used to highlight the task's card visually.
  • comments:{ text?: string, time?: Date, userId: string | number }[] - Comments about a task.
  • dueDate:Date - The task's due date.
  • priority:string - The task's priority.
  • progress:number - The task's progress in percentages - a number from 0 to 100.
  • startDate:Date - The task's start date.
  • status:string - The task's status. Has to correspond to the dataField of a column or sub-column from the columns property/array.
  • swimlane:string - The swimlane of the task. Has to correspond to the dataField of a swimlane from the swimlanes property/array, if it is defined.
  • tags:string - A comma-separated list of tags.
  • text:string - The text of the task.
  • userId:string | number - The ID of the user assigned to the task. Has to correspond to the id of an item from the users property/array.
DdataSourceMapSpecifies how the Kanban board's default fields (e.g., title, status, assignee) correspond to the fields in your data source. Use this mapping only if your data source uses field names that differ from the Kanban's expected keywords. If the field names already match, this mapping is optional. Note that only certain default fields support custom mapping; not all default mappings can be overridden.
DdragOffsetSpecifies the offset, in pixels, between the drag feedback element and the mouse cursor during task dragging operations. The value should be provided as an array: the first element sets the horizontal (x-axis) offset, and the second element sets the vertical (y-axis) offset, both relative to the cursor position. Alternatively, if set to 'auto', the system automatically calculates the offset based on the cursor’s position at the moment the drag action began. This allows for precise control over the visual positioning of the feedback element during drag-and-drop interactions.
EeditableControls whether tasks can be modified, including editing task details and assigning users to tasks. When enabled, users can update task information and manage task assignments; when disabled, tasks and their assigned users are read-only and cannot be changed programmatically or through the user interface.
EeditModeSpecifies how users can activate the task editing feature. The 'editBehavior' property accepts either '"singleClick"' or '"doubleClick"' as values:- '"singleClick"': Opens the dialog edit window when the user clicks once on a Kanban task.- '"doubleClick"' (default): Opens the dialog edit window when the user double-clicks on a Kanban task.By default, editing is triggered by a double-click. Use this setting to customize the interaction based on your application's needs.
FformatStringDateSets or retrieves the format string used to display the "Due date" label, as well as the date format for both the "Start date" and "Due date" editor fields. This determines how dates are shown and entered in these UI components.
FformatStringTimeSpecifies or retrieves the format string used to display the timestamp on comments. This determines how the date and time of each comment are presented (e.g., "YYYY-MM-DD HH:mm:ss").
HheaderPositionSets or retrieves the position of the header section within the user interface. The header typically contains interactive controls such as Customize, Filter, Sort, and Search buttons, allowing users to adjust and manipulate the displayed data according to their preferences.
HhierarchyDefines or retrieves how the column hierarchy is structured and displayed, specifying the method or format used to represent the relationships between columns within the component or dataset.
UunlockKeyGets or sets the unlockKey property, a unique key used to unlock or activate the product. This key is required to enable full access to product features.
LlocaleSets or retrieves the current locale (language and regional settings) used by the component. This property determines the language in which messages are displayed, and works together with the messages property, which provides localized message strings for each supported locale. Adjusting the locale will change the displayed text to correspond with the selected language from the messages definitions.
MmessagesDefines or retrieves an object containing the strings displayed in the widget, allowing for easy localization of text. This property works together with the locale property to support multiple languages and adapt the user interface based on the selected locale. Use this to provide translated labels, messages, and other widget text for internationalization.
OonTaskRenderCallback function that allows you to customize how tasks are rendered within the Kanban board. This function is invoked by the Kanban component and receives two arguments: 1. The HTML element representing the task (taskHtmlElement).2. The data object associated with the task (taskData).You can use this callback to modify the appearance, add event listeners, or inject additional content into the task's HTML element based on its data.
OonFilterPrepareCallback function that enables customization of the filter items displayed in the dropdown. It receives a single argument: an array containing all the items available for filtering. Within the function, you can modify this array—such as by updating, removing, or reordering items—to control which options appear in the filter dropdown and how they are presented to the user. The modified array will determine the final set of filter options shown in the UI.
OonSortPrepareA callback function that allows you to customize the items displayed in the sort dropdown menu. This function receives a single argument: an array containing all available sort options. You can modify this array—by removing, reordering, or updating items—to control which sorting options appear in the dropdown and how they are presented. The modified array will then be used to render the sort options to the user.
OonColumnHeaderRenderCallback function that allows customization of the column header rendering in the Kanban component. This function is invoked with three arguments: the column header's HTML element, the complete column data object, and the column's data field (a string representing the key associated with the column). Use this callback to modify or enhance the appearance and behavior of column headers as needed.
OonColumnFooterRenderCallback function that allows you to customize how the column footer is rendered in the Kanban component. This function is invoked with three arguments:1. The HTML element representing the column header2. The data object for the current column3. The field name associated with the column dataUse this callback to modify the footer's appearance or content based on the specific column's properties and data.
SselectionModeSpecifies how items can be selected within the component, such as allowing single selection, multiple selections, or disabling selection entirely.
SstoreHistorySpecifies whether the history of tasks is recorded and shown within the task dialog. When enabled, completed or previous tasks will be saved and displayed, allowing users to review their task activity directly in the dialog. When disabled, task history will not be retained or visible. This setting can be used to set or retrieve the current history display behavior.
SstoreHistoryItemsSpecifies the collection of task history items to be retrieved or updated when the storeHistory option is enabled. When storeHistory is true, this property determines which task history records are saved and accessed.
RrightToLeftSets or retrieves a value that determines whether the element’s alignment is configured for right-to-left (RTL) text direction, which is typically used in languages such as Arabic or Hebrew. When enabled, the element layout and text flow will support RTL locales, ensuring proper display for right-to-left scripts.
RreadonlyControls the read-only state of the edit dialog. When enabled, the dialog displays task details but disables all editing capabilities for those fields. However, if the comments feature is active, users can still add comments within the dialog, even while other fields remain uneditable.
SswimlanesProvides a detailed configuration of swimlanes on the Kanban board, specifying how tasks are grouped horizontally by categories such as assignee, priority, or project. When swimlanes are enabled, sub-columns within each column are disabled to maintain a clear visual separation of items across swimlanes. Click for more details. Property object's options:
  • color:string - The swimlane's color.
  • dataField:string - Sets or gets the swimlane's data source bound field. Corresponds to the swimlane field in the data source.
  • label:string - Sets or gets the text displayed in the swimlane.
SswimlanesFromSpecifies or retrieves the zero-based index of the column where the swimlanes should begin. This determines the starting position for rendering swimlanes within a grid or table layout.
SswimlanesToSpecifies or retrieves the zero-based index of the column where the swimlanes should terminate. By default, swimlanes extend to the final column in the layout. Setting this property allows you to control at which column the swimlanes will stop, providing flexibility in customizing the swimlane display.
TtagsSpecifies the permitted tags that can be used. When this property is set, only the listed tags will be allowed; if no tags are specified, all tags provided by the data source are accepted by default. This property can be used to restrict or expand the selection of allowed tags as needed.
TtaskActionsControls whether the task actions icon is displayed or hidden, allowing users to show or conceal the icon based on their preferences or application state.
TtaskActionsRenderedDefines a callback function that is invoked whenever the task actions menu is generated in the UI. This function receives the actions menu element as its parameter, enabling you to modify or extend the menu's content and behavior. For example, you can insert custom menu items, attach event listeners, or alter existing elements within the menu.'Example usage:''''js(list) => { // Add a custom menu item list.innerHTML = '
Custom Item
'; // Attach a click handler to the menu list.onclick = () => { alert('Custom item clicked'); };}'''This callback provides full access to the task actions menu element, empowering you to tailor the menu to fit your specific requirements.
TtaskCommentsControls whether the task comments icon is displayed or hidden, allowing you to show or conceal the icon associated with task comments.
TtaskDueControls whether the task due date icon is shown or hidden in the interface. When enabled, the icon indicating a task's due date will be visible; when disabled, the icon will be hidden from view.
TtaskPositionDetermines whether tasks are displayed across all levels of the column hierarchy or are restricted to only the leaf (lowest-level) columns. When enabled, tasks can be shown in any column within the hierarchy; when disabled, tasks are displayed exclusively in the leaf columns. This setting allows you to control the visibility of tasks based on the column hierarchy structure.
TtaskPriorityControls whether the task priority icon is displayed. The icon appears when a task is marked as either low or high priority. Disabling this option will hide the icon regardless of the task’s priority status.
TtaskProgressControls whether the task progress bar and the label displaying the number of completed sub-tasks are shown or hidden. When enabled, both visual elements will be visible; when disabled, they will be hidden from view.
TtaskCustomFieldsDefines which custom fields are shown on a task card and how they appear. This property accepts an array of objects, where each object represents a custom field configuration with the following properties:- 'dataField' (string, required): Specifies the unique key or identifier for the custom field. This determines which value will be displayed on the card.- 'label' (string, required): The display name or title of the field as it appears on the card.- 'dataType' (string, required): Indicates the field's data type (e.g., 'string', 'number', 'date'). Used to determine how the field value should be formatted or displayed.- 'visible' (boolean, optional): If set to 'true', the field is displayed on the card; if 'false', it is hidden. Defaults to 'true' if omitted.- 'image' (boolean, optional): Set to 'true' if the field value is an image URL or Base64 string. This tells the UI to render the value as an image instead of text.- 'cover' (boolean, optional): When 'image' is 'true', setting 'cover' to 'true' will display the image as the card’s cover image (typically at the top of the card).'Example usage:''''json[ { "dataField": "title", "label": "Task Title", "dataType": "string", "visible": true }, { "dataField": "dueDate", "label": "Due Date", "dataType": "date" }, { "dataField": "avatar", "label": "Assignee Photo", "dataType": "string", "image": true, "visible": true }, { "dataField": "coverImage", "label": "Project Cover", "dataType": "string", "image": true, "cover": true }]'''This configuration determines which fields are shown, how they're labeled, their format, and whether any field displays an image or acts as a cover image on the task card.
TtaskColorEntireSurfaceThe background color of a task is determined by its individual color property. By default, this color is visually represented as an accent along the left border of the task element, rather than filling the entire background. This design helps differentiate tasks based on their assigned colors while maintaining a consistent overall appearance.
TtaskSubTasksInputDisplays an input field within the task card, allowing users to dynamically add sub-tasks to the main task. To enable this feature, ensure that the 'taskSubTasks' property is set to a value other than 'none'. When 'taskSubTasks' is appropriately configured, users will see and be able to use the sub-task input interface.
TtaskSubTasksSpecifies how sub-tasks are rendered within a task card. - '"none"' *(default)*: Sub-tasks are hidden on the task card and are only visible within the edit dialog. - '"onePerRow"': All sub-tasks associated with the task are displayed directly on the task card, with each sub-task shown on its own row. - '"onlyUnfinished"': Only sub-tasks that are not marked as completed are displayed on the task card; completed sub-tasks remain hidden.
TtaskTagsControls whether task tags are shown or hidden in the user interface, allowing users to display or conceal tag information associated with each task.
TtaskUserIconControls whether the task user icon is displayed or hidden, allowing you to show or hide the icon representing the user associated with a task.
TtextTemplateSpecifies the template to use for rendering task text. This property accepts multiple value types:- A string starting with #, which references the id of a