Kanban

avonni-dd-kanban

The Avonni Data Driven Kanban displays records in a kanban format.

Overview

Kanban is a data-driven Lightning Web Component that displays Salesforce records as cards organized into columns, grouped by a field value.

The Kanban is query mode only: you supply a query describing which records to fetch, and a mapping that turns each returned record into a card. Cards are distributed into columns based on the group-field-name, and users can drag cards between columns to update the grouping field. There is no static-items mode—the component always reads its data from a live query.

Use Cases

• Sales pipeline: Show opportunities as cards grouped by stage.
• Case management: Track support cases by status column.
• Task boards: Organize tasks or to-dos by their current state.
• Project tracking: Move records through workflow phases via drag and drop.
• Lead qualification: Group leads by rating or status and reprioritize visually.
• Inventory or order flow: Visualize records moving through fulfillment stages.

---

Use Case Examples

Example 1: Query mode

Scenario: Display opportunities as cards grouped by stage, with an amount summary in each column header and drag-and-drop to change stages.

<!-- pipelineBoard.html -->
<template>
    <avonni-dd-kanban
        actions={actions}
        avatar-attributes={avatarAttributes}
        fields={opportunityFields}
        filters={opportunityFilters}
        group-field-name="StageName"
        header-actions={headerActions}
        header-title="Opportunities by stage"
        items-per-page="50"
        mapping={opportunityMapping}
        query={opportunityQuery}
        search-fields={opportunitySearchFields}
        show-item-count
        summary-field-name="Amount"
        variant="base"
        onactionclick={handleActionClick}
        onitemdrop={handleItemDrop}
        onerror={handleError}
    ></avonni-dd-kanban>
</template>

// pipelineBoard.js
import { LightningElement } from 'lwc';

export default class PipelineBoard extends LightningElement {
    opportunityQuery = {
        objectApiName: 'Opportunity',
        orderBy: 'CloseDate ASC',
        limit: 50
    };
    opportunityMapping = {
        name: '{{Record.Id}}',
        title: '{{Record.Name}}',
        description: '{{Record.StageName}}',
        endDate: '{{Record.CloseDate}}',
        avatar: { fallbackIconName: 'standard:opportunity' }
    };
    opportunityFields = ['Amount', 'CloseDate'];
    opportunityFilters = ['StageName', 'ForecastCategoryName'];
    opportunitySearchFields = ['Name'];
    avatarAttributes = { fallbackIconName: 'standard:opportunity', variant: 'circle', size: 'medium' };
    headerActions = [{ label: 'Refresh', name: 'refresh', iconName: 'utility:refresh' }];
    actions = [
        { label: 'See more', name: 'seeMore' },
        { label: 'Delete', name: 'delete' }
    ];

    handleItemDrop(event) {
        const { groupValue, record } = event.detail; // record moved to groupValue
    }

    handleActionClick(event) {
        const { name, record } = event.detail;
    }

    handleError(event) {
        const message = event.detail.message;
    }
}

Result: A kanban with one column per opportunity stage, each card showing the opportunity name, amount, and close date. Column headers show the item count and total amount; dragging a card to a new column fires itemdrop with the new stage value.

Example 2: Query mode with subgroups and path variant

Scenario: Track support cases by status using the path variant, with cases subgrouped by priority inside each column.

<!-- caseBoard.html -->
<template>
    <avonni-dd-kanban
        fields={caseFields}
        group-field-name="Status"
        sub-group-field-name="Priority"
        header-title="Cases by status"
        mapping={caseMapping}
        query={caseQuery}
        show-item-count
        show-subgroup-item-count
        variant="path"
        onitemdrop={handleItemDrop}
    ></avonni-dd-kanban>
</template>

// caseBoard.js
import { LightningElement } from 'lwc';

export default class CaseBoard extends LightningElement {
    caseQuery = {
        objectApiName: 'Case',
        orderBy: 'CreatedDate DESC',
        limit: 100
    };
    caseMapping = {
        name: '{{Record.Id}}',
        title: '{{Record.Subject}}',
        description: '{{Record.Status}}',
        avatar: { fallbackIconName: 'standard:case' }
    };
    caseFields = ['Priority', 'CaseNumber'];

    handleItemDrop(event) {
        const { groupValue, record } = event.detail; // case moved to new status
    }
}

Result: A path-style board with a column per case status, each split into priority subgroups with their own counts. Moving a card updates its status via the itemdrop event.

---

Specifications

Attributes

Name	Description	Type	Default	Required
actions	Array of action objects. The actions are displayed on the right of every card. On click on an action, the actionclick event is fired.	DdKanbanAction[]	—
avatar-attributes	Object defining how the items avatars are displayed. This is the default attributes applied to all the items. They can be overridden for specific items by their mapping.	DdKanbanCardAvatarAttributes	—
card-attributes	Object defining the way the static items should be mapped to the kanban item properties.	DdKanbanCardAttributes	—
column-order-direction	Object defining the order of the columns.	DdKanbanColumnOrderDirection	—
disable-column-drag-and-drop	If true, the columns cannot be dragged by users.	Boolean	false
disable-item-drag-and-drop	If true, the items cannot be dragged by users.	Boolean	false
fields	Array of field API names that belong to the queried object. The fields will be displayed on the kanban cards, with their corresponding values.	string[]	—
fields-attributes	Object defining the fields layout.	DdKanbanFieldsAttributes	—
filters	Array of field API names that belong to the queried object. These fields will be displayed as user filters.	string[]	—
filters-attributes	Object defining the filters-specific attributes.	DdElementFiltersAttributes	—
group-by-attributes	Object defining the group by attributes.	DdKanbanGroupByAttributes	—
group-field-name	API name of the field to group the items.	String	—	Yes
groups	Array of group objects defining the columns. Used in static mode to define the columns directly. In query mode, the columns are derived from the picklist values of the groupFieldName field.	DdKanbanGroup[]	—
header-actions	Array of actions to display at the top right of the header. On click on a header action, the headeractionclick event is fired.	DdElementAction[]	—
header-avatar	Avatar displayed at the top left of the header.	DdElementAvatar	—
header-caption	Header caption, displayed above the title.	String	—
header-help-text	If present, a help text icon is displayed next to the header title. On focus or hover on the icon, the header help text is displayed in a tooltip.	String	—
header-help-text-attributes	Object defining the help text-specific attributes.	DdElementHelpTextAttributes	—
header-metric-aggregation-fields	Array of aggregation query definitions, used to display metrics in the header.	DdElementHeaderMetricAggregationField[]	—
header-title	Main title displayed in the header.	String	—
header-visible-actions-count	Number of header actions that appear as regular buttons. Remaining actions appear in a dropdown menu.	integer	—
hide-column-header	If true, the column headers are hidden.	Boolean	false
image-attributes	Object defining the image layout.	DdKanbanImageAttributes	—
items	Array of static items displayed in the kanban. When this property is set, the kanban ignores the query and mapping properties and displays the items directly. Each item must be an object with the fields defined in the fields property.	object[]	—
items-per-page	If the pagination is enabled, number of items per page. Otherwise, number of items loaded at once.	integer	100
key-field	Name of the field in each item used as its unique key. Used in static mode.	String	—
mapping	Object defining the way the records returned by the query should be mapped to the kanban item properties. To insert the value of a field, use the syntax {{Record.FieldApiName}}. For example, to use the value of the Name field, use {{Record.Name}}.	DdKanbanMapping	—
query	Definition of the query to execute to get the records that will be mapped.	DdElementQuery	—
refresh-emp	Object describing a platform event that should be subscribed to in order to refresh the component when an event is published.	DdElementRefreshEmp	—
search-attributes	Object defining the search-specific attributes.	DdElementSearchAttributes	—
search-fields	Array of field API names that can be used by the search box to filter the records. The fields must belong to the queried object, and they must be filterable.	string[]	—
show-item-count	If true, the item count is displayed in the column header.	Boolean	false
show-subgroup-item-count	If true, the subgroup item count is displayed in the column header.	Boolean	false
side-panel-attributes	Object defining the side panel-specific attributes.	DdElementSidePanelAttributes	—
sub-group-field-name	API name of the field to subgroup the items.	String	—
sub-groups	Array of subgroup objects defining the rows within each column. Used in static mode to define the subgroups directly. In query mode, the subgroups are derived from the picklist values of the subGroupFieldName field.	DdKanbanGroup[]	—
summary-field-name	API name of the field to summarize the items in the column header.	String	—
summary-type-attributes	Object defining the summary type.	DdKanbanSummaryTypeAttributes	—
variant	The variant changes the appearance of the kanban. Valid values are base and path.	String	"base"

Mapping

The mapping object converts each queried record into a card. Insert a field value with the {{Record.FieldApiName}} syntax. The most useful mapping keys are:

• name — unique key of the card, usually {{Record.Id}}.
• title — the card heading, e.g. {{Record.Name}}.
• description — secondary text under the title.
• endDate — drives the card's due date display.
• imageSrc — cover image URL for the card.
• avatar — an avatar object, e.g. { fallbackIconName: 'standard:opportunity' }.

const OPPORTUNITY_MAPPING = {
    name: '{{Record.Id}}',
    title: '{{Record.Name}}',
    description: '{{Record.StageName}}',
    endDate: '{{Record.CloseDate}}',
    avatar: { fallbackIconName: 'standard:opportunity' }
};

Methods

Name	Description	Argument Name	Argument Type	Argument Description
refresh	Refresh the query and the records displayed in the component.	stayOnCurrentPage	Boolean	If true, the component will refresh but stay on the current page.

Custom Events

actionclick

Event fired when an item action is clicked.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
item	object	Kanban item that the action belongs to, without its mapped properties.
record	object	Record corresponding to the item the action belongs to.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

error

The event fired when an error occurs in the component.

The error event returns the following parameters.

Parameter	Type	Description
message	string	Message of the error.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

filter

The event fired when the user filters the records.

The filter event returns the following parameters.

Parameter	Type	Description
value	object	Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

headeractionclick

The event fired when a header action is clicked.

The headeractionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

itemclick

Event fired when an item is clicked.

The itemclick event returns the following parameters.

Parameter	Type	Description
item	object	Kanban item that was clicked, without its mapped properties.
record	object	Record corresponding to the item that was clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

itemdrop

Event fired when an item is dropped on a column.

The itemdrop event returns the following parameters.

Parameter	Type	Description
groupValue	string	Value of the group the item was dropped on.
item	object	Kanban item that was dropped, without its mapped properties.
record	object	Record corresponding to the item that was dropped.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

nbitemschange

The event fired when the number of items displayed in the component changes.

The nbitemschange event returns the following parameters.

Parameter	Type	Description
value	integer	Number of items displayed in the component.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

actionclick

Event fired when an item action is clicked.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.
record	object	Record corresponding to the item the action belongs to.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

error

The event fired when an error occurs in the component.

The error event returns the following parameters.

Parameter	Type	Description
message	string	Message of the error.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

filter

The event fired when the user filters the records.

The filter event returns the following parameters.

Parameter	Type	Description
value	object	Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

headeractionclick

The event fired when a header action is clicked.

The headeractionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

itemclick

Event fired when an item is clicked.

The itemclick event returns the following parameters.

Parameter	Type	Description
record	object	Record corresponding to the item that was clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

itemdrop

Event fired when an item is dropped on a column.

The itemdrop event returns the following parameters.

Parameter	Type	Description
groupValue	string	Value of the group the item was dropped on.
record	object	Record corresponding to the item that was dropped.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

nbitemschange

The event fired when the number of items displayed in the component changes.

The nbitemschange event returns the following parameters.

Parameter	Type	Description
value	integer	Number of items displayed in the component.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

pagechange

The event fired when the page changes.

The pagechange event returns the following parameters.

Parameter	Type	Description
value	integer	New page number.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-dd-kanban-header-actions-color-background	color	—
--avonni-dd-kanban-header-actions-color-background-active	color	—
--avonni-dd-kanban-header-actions-color-background-hover	color	—
--avonni-dd-kanban-header-actions-color-border	color	—
--avonni-dd-kanban-header-actions-color-border-active	color	—
--avonni-dd-kanban-header-actions-color-border-hover	color	—
--avonni-dd-kanban-header-actions-text-color	color	—
--avonni-dd-kanban-header-actions-text-color-active	color	—
--avonni-dd-kanban-header-actions-text-color-hover	color	—
--avonni-dd-kanban-header-caption-font-family	string	—
--avonni-dd-kanban-header-caption-font-size	dimension	—
--avonni-dd-kanban-header-caption-font-style	string	normal
--avonni-dd-kanban-header-caption-font-weight	number	400
--avonni-dd-kanban-header-caption-letter-spacing	string	—
--avonni-dd-kanban-header-caption-line-height	string	—
--avonni-dd-kanban-header-caption-text-color	color	#000000
--avonni-dd-kanban-header-color-background	color	—
--avonni-dd-kanban-header-color-border	color	—
--avonni-dd-kanban-header-color-border-bottom	color	#c9c9c9
--avonni-dd-kanban-header-icon-color-background	color	—
--avonni-dd-kanban-header-icon-color-foreground	color	—
--avonni-dd-kanban-header-icon-color-foreground-default	color	—
--avonni-dd-kanban-header-icon-radius-border	string	—
--avonni-dd-kanban-header-margin-block-end	dimension	—
--avonni-dd-kanban-header-radius-border	string	—
--avonni-dd-kanban-header-sizing-border	string	—
--avonni-dd-kanban-header-sizing-border-bottom	dimension	1px
--avonni-dd-kanban-header-spacing-block-end	dimension	0.75rem
--avonni-dd-kanban-header-spacing-block-start	dimension	0.75rem
--avonni-dd-kanban-header-spacing-inline-end	dimension	1rem
--avonni-dd-kanban-header-spacing-inline-start	dimension	1rem
--avonni-dd-kanban-header-styling-border	string	—
--avonni-dd-kanban-header-styling-border-bottom	string	solid
--avonni-dd-kanban-header-title-font-family	string	—
--avonni-dd-kanban-header-title-font-size	dimension	1rem
--avonni-dd-kanban-header-title-font-style	string	normal
--avonni-dd-kanban-header-title-font-weight	number	400
--avonni-dd-kanban-header-title-letter-spacing	string	—
--avonni-dd-kanban-header-title-line-height	number	1.25
--avonni-dd-kanban-header-title-text-color	color	#080707

Key Considerations

• Query mode only: The Kanban always reads data from a live query—there is no static-items mode. The query, mapping, and group-field-name are required.
• Grouping field: group-field-name should reference a picklist (or similarly low-cardinality field) so columns stay meaningful and manageable.
• Persisting drops: Dragging a card fires itemdrop with the new group value, but your component is responsible for saving that change back to the record.
• Drag control: Use disable-column-drag-and-drop and disable-item-drag-and-drop to lock down reordering where it isn't wanted.
• Mapping syntax: Field values must use the {{Record.FieldApiName}} syntax, and every field referenced in the mapping or fields must exist on the queried object.
• Best Practice: Always set group-field-name to a picklist field whose values map cleanly to columns, and keep fields focused on the few values that matter on a card to avoid clutter.

---

Troubleshooting Common Issues

• No columns appear: Confirm group-field-name is a valid field on the queried object and that the query returns records with non-null values for it.
• Cards are blank: Verify the mapping uses {{Record.FieldApiName}} syntax and that referenced fields are accessible to the running user.
• Drag does nothing on save: itemdrop only reports the new group value—wire the event to update the record yourself; also check the drag-and-drop properties are not disabled.
• If issues persist: Contact our support team at [email protected] for assistance.