> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# list-item

> One option as a card with an optional image, a title, a subheading, and a short description

`list-item` renders one option the end user can pick: a product, a room, a menu item, an article. Use one block per item and at most 10 per reply. The platform teaches this block on every text channel; see [Response formatting](https://docs.heylua.ai/channels/formatting/overview.md) for when the model uses it on its own.

*Verified against lua-cli 3.33.0.*

## Syntax

```text theme={null}
::: list-item
![image](https://cdn.example.com/item.jpg)
# Item title
## Subheading
One or two sentences of description.
:::
```

## Fields

| Field | Required | Notes |
| - | - | - |
| `![image](url)` | No | Public HTTPS URL. |
| `# Title` | Yes | Unique per reply; `#Title` without the space also parses. |
| `## Subheading` | Yes | Price, availability, or category; the model is asked for one. |
| Remaining lines | No | Description, about 40 words at most. |

## Example

A buy flow is the common shape: cards for the options, then the next step. In the skill's `context`, one sentence makes the model emit it: "When you show products, send each as a `::: list-item` with the price as the subheading, then a `::: actions` block with the next steps; once the customer has chosen, return the checkout URL from `create_checkout` in a `::: payment` block."

```text theme={null}
Two laptops match what you need.

::: list-item
![image](https://cdn.example.com/laptop-pro.jpg)
# UltraBook Pro
## $1,299 · In stock
16 GB RAM, 512 GB SSD, 14-inch display. Free two-day shipping.
:::

::: list-item
![image](https://cdn.example.com/laptop-air.jpg)
# UltraBook Air
## $899 · In stock
8 GB RAM, 256 GB SSD, 13-inch display.
:::

::: actions
- Buy the UltraBook Pro
- Buy the UltraBook Air
- Compare the two
:::
```

![Two list-item cards rendered in the web widget](https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/formatting/formatted-response-example.png?fit=max\&auto=format\&n=5airD3u2P6mv3Ovl\&q=85\&s=9500b90fb1ad67a7353b50222c092625)

list-item cards in the web widget

On WhatsApp the same reply differs in three ways: a single `list-item` is sent as bold text rather than a card, three or more `actions` become a list whose rows read **Option 1**, **Option 2**, … with your entry as the description, and the `payment` block that follows the choice is a button labeled **Pay Now** whatever label you wrote.

## Where it renders

| Channel | Behavior |
| - | - |
| Web widget | Cards; consecutive blocks render as one group |
| WhatsApp | Interactive list, 9 rows per message; or one image message per item with a **Select** button when every item has an image |
| Messenger, Instagram | Generic templates |
| Slack | Sections with title, subheading, and description; items with an image also get the image and a **Select** button |
| Teams | Adaptive Card containers with a **Select: title** action |
| RCS | Rich cards |
| MessageBird | List |
| Email (your own address) | Card with the image, title, subheading, and description |
| iMessage | Title, subheading, and description as text, then the image |
| SMS, Front, email (generated inbox) | One `title — subheading — description` line per card; a reply with a single card sends it as text |

On WhatsApp a list row shows the title cut at 24 characters and the subheading and description cut at 72, and a reply with more than 9 items is split across messages with a page indicator. Tapping an item sends a message that names it back to the agent: the title on Slack and Teams, the title and subheading in the web widget, and a sentence such as `I selected: *UltraBook Pro* (…)` with the title and details on WhatsApp, Messenger, and Instagram.

On the messaging channels a reply whose only block is a single `list-item` is sent as text with the title in bold, plus its image, rather than as a card; send two or more items for cards.

## See also

* [Response formatting](https://docs.heylua.ai/channels/formatting/overview.md) — the per-channel matrix
* [horizontal-list-item](https://docs.heylua.ai/channels/formatting/horizontal-list-item.md) — the same fields as a carousel
* [actions](https://docs.heylua.ai/channels/formatting/actions.md) — follow-up buttons after a list


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.