> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/data-driven-components/kanban.md).

# 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.

```html
<!-- 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>
```

```js
// 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.

```html
<!-- 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>
```

```js
// 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             | —        |          |
| `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-field-name`                 | API name of the field to group the items.                                                                                                                                                                                                                   | String                                   | —        | Yes      |
| `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-per-page`                   | If the pagination is enabled, number of items per page. Otherwise, number of items loaded at once.                                                                                                                                                          | integer                                  | `100`    |          |
| `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                                   | —        |          |
| `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' }`.

```js
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.                             |
| `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 <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/data-driven-components/kanban.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.