> 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 runs in one of two modes. In **query mode** you supply a `query` describing which records to fetch and a `mapping` that turns each returned record into a card. In **static mode** you supply `items` directly, together with a `key-field` and `card-attributes`, and the `query` and `mapping` properties are ignored; `groups` and `sub-groups` then define the columns and swimlanes explicitly. In both modes, cards are distributed into columns based on the `group-field-name`, and users can drag cards between columns to update the grouping field.

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

***

{% hint style="info" %}
**See it in a real project**

[Listings board](https://docs.avonnicomponents.com/projects/use-cases/boards-and-pipelines/listings-board): A listings board by stage, one swimlane per agent, totals per column.
{% endhint %}

## 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-aggregate-fields={groupAggregateFields}
        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
        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' }
    };
    groupAggregateFields = [{ fieldName: 'Amount', aggregateFunction: 'SUM', type: 'currency' }];
    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: save the record in the handler, the component does not.

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2FOjN69iVU92gK5qNMHBTM%2Fkanban-example-opportunities.png?alt=media" alt="A kanban board of opportunities with one column per stage, each header showing its card count and the total amount, and cards with name, stage, amount and close date"><figcaption><p>Example 1 on sample opportunities: every stage of the picklist gets a column, so the board scrolls sideways past the empty ones, and each column scrolls its own cards.</p></figcaption></figure>

### 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 fires `itemdrop` with the new status: save it in the handler.

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2F2iVzyUpyijVrv8ozBVwA%2Fkanban-example-cases.png?alt=media" alt="A path-style kanban of cases with one column per status and High, Medium and Low priority rows, each with its own count"><figcaption><p>Example 2 on sample cases: the path across the top, and one row per priority inside each status.</p></figcaption></figure>

***

## 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-aggregate-fields`           | Array of aggregate field definitions displayed as summaries in each group header in query mode.                                                                                                                                                             | DdKanbanGroupAggregateField\[]           | —        |          |
| `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-aggregate-fields`       | Array of aggregate field definitions displayed as summaries in each subgroup (swimlane) header in query mode.                                                                                                                                               | DdKanbanGroupAggregateField\[]           | —        |          |
| `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' }`.

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

### Group Summaries

In query mode, column and swimlane headers can show aggregated values. `group-aggregate-fields` defines the summaries displayed in each column header, and `sub-group-aggregate-fields` does the same for each subgroup (swimlane) header. Each definition accepts:

* `fieldName` — required API name of the field to aggregate.
* `aggregateFunction` — `SUM`, `AVG`, `COUNT`, `COUNT_DISTINCT`, `MIN`, or `MAX`. Defaults to `SUM`.
* `prefix` and `suffix` — text displayed before and after the aggregated value.
* `treatBlankValueAsZero` — treat blank values as zero in the aggregation. Defaults to `false`.
* `type` — display type of the value: `currency`, `number`, or `percent`.
* `typeAttributes` — type-specific formatting options for the displayed value.

```js
const GROUP_AGGREGATE_FIELDS = [
    {
        fieldName: 'Amount',
        aggregateFunction: 'SUM',
        prefix: 'Total',
        type: 'currency',
        typeAttributes: { currencyCode: 'USD' }
    },
    {
        fieldName: 'Id',
        aggregateFunction: 'COUNT',
        suffix: 'opportunities',
        type: 'number'
    }
];
```

Aggregate fields take precedence over the single-value summary produced by `summary-field-name`. Call the `refreshSummaries` method to re-run the aggregate queries without reloading the cards.

### 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. |
| `refreshSummaries` | Refresh the aggregated summaries values by re-running the queries. |                     |               |                                                                   |

### 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.                  |
| `subGroupValue` | string | Value of the subgroup 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.                        |

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

* **Static mode needs groups:** In static mode, set `items`, `card-attributes` and `key-field`, and define the columns with `groups`: the columns come only from it.
* **Grouping field:** In query mode, `group-field-name` must be a picklist field: the columns come only from its picklist values.
* **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.
* **`item` and `record` depend on the mode:** `actionclick`, `itemclick` and `itemdrop` all carry both, but only one of them is filled — in query mode `record` holds the record and `item` is `null`; in static mode `item` holds the static item and `record` is `null`.
* **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.
* **Card avatars:** `avatar-attributes` sets the avatar of every card, and it takes precedence over the avatar an item's own mapping defines — the two are merged with the component-level attributes applied last. The generated description above states the opposite; the behaviour described here is the one in the component.
* **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 picklist field on the queried object. In query mode the columns come only from its picklist values, so any other field type produces no columns.
* **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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.