# Cards

<div><figure><img src="/files/I8uvsVE02VY4nxUBAGcI" alt=""><figcaption></figcaption></figure> <figure><img src="/files/2MIQsv2A6AFzCdJIAg7R" alt=""><figcaption></figcaption></figure></div>

Displays one or more card-style panels in a grid or list format.\
Cards can contain an image, a title, a description, tooltips on hover, and interactive buttons or keybind actions.

***

## Structure

```lua
left = {
    type = "cards",
    title = "Items",
    layout = {
        columns = 2,
        flex = "column",
        scroll_x = "none"
    },
    cards = {
        {
            image = "https://placehold.co/252x126",
            title = "My Card",
            description = "This is a test card.",
            layout = "column",
            on_hover = {
                title = "Extra Info",
                description = { "You can use", "- multiple lines", "- like this" },
                values = {
                    { key = "Item", value = "Something" },
                    { key = "Owner", value = "Case" }
                },
                actions = {
                    {
                        id = "inspect_item",
                        key = "E",
                        label = "Inspect",
                        on_action = function(data)
                            -- Inspect logic
                        end
                    }
                },
                rarity = "common"
            },
            buttons = {
                {
                    id = "edit_card",
                    label = "Edit",
                    class = "primary",
                    on_action = function(data)
                        -- Edit card logic
                    end,
                    dataset = {
                        card_id = "card_1"
                    }
                },
                {
                    id = "close_ui",
                    label = "Close",
                    action = "close_builder",
                    class = "danger"
                }
            }
        }
    }
}
```

***

## Card Options

Each card supports the following fields:

| Key             | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| `title`         | Title text for the card.                                                  |
| `description`   | Text shown below the title.                                               |
| `image`         | (Optional) Image shown at the top. Full URLs or `nui://` paths supported. |
| `layout`        | (Optional) `"column"` or `"row"` layout inside the card.                  |
| `on_hover`      | (Optional) Shows tooltip with extra info:                                 |
| → `title`       | Tooltip header.                                                           |
| → `description` | List of lines for the tooltip.                                            |
| → `values`      | Array of `{ key, value }` to show below tooltip.                          |
| → `actions`     | Keybinding actions with `on_action` support.                              |
| → `rarity`      | (Optional) A style tag such as `"common"`, `"rare"`, etc.                 |
| `buttons`       | (Optional) Array of button objects (same structure as Buttons component). |

***

## Layout Options

| Key        | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `columns`  | Number of columns in the card layout (e.g., `2`).          |
| `flex`     | `"row"` or `"column"` for internal card layout.            |
| `scroll_x` | `"auto"`, `"on"`, or `"none"` to enable horizontal scroll. |
| `scroll_y` | `"auto"`, `"on"`, or `"none"` to enable vertical scroll.   |

***

## Notes

* Cards are perfect for displaying item lists, inventories, player entries, or shops.
* You can freely mix images, hover tooltips, and buttons per card.
* Each `button` or `action` supports:
  * `on_action = function(data)` — your custom logic.
  * `action = "close_builder"` — a built-in safe UI close.
  * Optional `dataset = {}` to pass values to the function.
* This structure keeps your logic uniform across both `cards.buttons` and `cards.on_hover.actions`.


---

# Agent Instructions: 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:

```
GET https://docs.boii.dev/fivem-free-resources/bduk/components/cards.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.