# Cards

<div><figure><img src="https://3046942752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHfd391cB6wDC8S3yHcie%2Fuploads%2FzxUn8nDnw7Oz77Py2eec%2Fimage.png?alt=media&#x26;token=5866de8c-fb20-42db-ab10-1e1cd411d57f" alt=""><figcaption></figcaption></figure> <figure><img src="https://3046942752-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHfd391cB6wDC8S3yHcie%2Fuploads%2FjxVyFWOk1mnA29hfX4t2%2Fimage.png?alt=media&#x26;token=ffbc2089-9537-4e48-9725-eccda3906d88" 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`.