# Elements

Text, button, toggle, input, chart and table in messages: fields, values and sizes.

You attach these six elements to a [message](https://packlets.app/en/docs/nachrichten-elemente.md), in the `elements` field of [`POST /v1/push`](https://packlets.app/en/docs/api-push.md). Up to 12 per message.

## Overview

| `type` | Element | Used for | Value | Interactive |
|---|---|---|---|---|
| `text` | [Text](#text) | Heading, paragraph, or note | the text | no |
| `button` | [Button](#button) | Trigger an action | – | yes, on every tap |
| `toggle` | [Toggle](#toggle) | Switch something on or off | `true` or `false` | yes, on every flip |
| `input` | [Input](#input) | Send text to your tool | the text | yes, on submit |
| `chart` | [Chart](#chart) | Numbers as bars or a line | the points | no |
| `table` | [Table](#table) | Data in rows and columns | the rows | no |

**Value** is what your tool passes along when sending. For toggles and inputs, it changes when you use them in the app; Packlets stores it. Your tool can no longer change values in a message that has been sent. **Interactive** means: every interaction goes to your webhook as a [`ui` event](https://packlets.app/en/docs/ereignisse.md#element-used-ui) with the `message_id`.

## Common fields

| Field | Type | Required | Meaning |
|---|---|---|---|
| `type` | one of the six types | yes | Kind of element. |
| `id` | 1 to 40 characters: letters, digits, `_`, `-` | yes | Your identifier, unique per message. Comes back in the webhook as `element_id`. |
| `width` | integer 1 to 6 | no | Width in columns. Default 6, the full width. |
| `height` | number in points | no | Minimum height. Not for `text`. |

How width and height work together is covered under [Layout](https://packlets.app/en/docs/layout.md).

## Text

| Field | Type | Required | Meaning |
|---|---|---|---|
| `text` | text, 1 to 2,000 characters | yes | The content. |
| `style` | `title`, `body`, or `caption` | no | Heading, paragraph (default), or small gray note. |

- **Value:** the text.
- **Size:** at least 2 columns wide. The height follows the content, there is no `height`.
- For `body`, the same [formatting](https://packlets.app/en/docs/senden.md#formatting) applies as in the message text.

```json
{ "type": "text", "id": "stand", "text": "Last checked at 9:41", "style": "caption" }
```

## Button

| Field | Type | Required | Meaning |
|---|---|---|---|
| `label` | text, 1 to 40 characters | yes | Label. |
| `style` | `primary` or `secondary` | no | Dark (default) or light. |

- **Value:** none. A tap sends the `ui` event with `value: null`.
- **Size:** at least 2 columns wide, height 44 to 240.
- A button can be tapped any number of times. That sets it apart from the [button](https://packlets.app/en/docs/knoepfe.md) in the `buttons` field.

```json
{ "type": "button", "id": "restart", "label": "Restart", "width": 3 }
```

## Toggle

| Field | Type | Required | Meaning |
|---|---|---|---|
| `label` | text, 1 to 60 characters | yes | Label. |
| `description` | text, up to 160 characters | no | Explanation below the label. |
| `value` | `true` or `false` | no | Initial value. Default `false`. |

- **Value:** `true` or `false`. Every flip sends the `ui` event with the new value.
- **Size:** at least 3 columns wide, height 64 to 240.

```json
{ "type": "toggle", "id": "wartung", "label": "Show maintenance page", "value": true }
```

## Input

| Field | Type | Required | Meaning |
|---|---|---|---|
| `label` | text, 1 to 60 characters | yes | Label. |
| `placeholder` | text, up to 80 characters | no | Gray example text in the empty field. |
| `button` | text, 1 to 30 characters | no | Label of the submit button. If omitted, the app shows "Send" or "Senden", depending on the phone's language. |
| `value` | text, up to 500 characters | no | Initial value. Default empty. |

- **Value:** the text, up to 500 characters. The `ui` event only arrives on submit, not on every letter.
- **Size:** at least 3 columns wide, height 160 to 400.

```json
{ "type": "input", "id": "antwort", "label": "Reply to Lena", "placeholder": "e.g. Ships today", "button": "Reply" }
```

## Chart

| Field | Type | Required | Meaning |
|---|---|---|---|
| `label` | text, 1 to 60 characters | yes | Title of the card. |
| `chart` | `bar` or `line` | no | Bars (default) or line. |
| `unit` | text, up to 8 characters | no | Unit after the value at the top right. |
| `points` | list, up to 31 points | no | Per point `{"label": "Mon", "value": 3.5}`. `label` up to 12 characters, `value` a number. Default empty. |
| `highlight` | integer from 0 | no | Which point is highlighted, counted from 0. Default: the last one. |

- **Value:** the points.
- **Size:** at least 3 columns wide, height 120 to 480.
- With many points, the app shows only every second or third label.

```json
{
  "type": "chart", "id": "umsatz", "label": "Revenue", "unit": "€",
  "points": [{ "label": "Mon", "value": 860 }, { "label": "Tue", "value": 1204 }]
}
```

## Table

| Field | Type | Required | Meaning |
|---|---|---|---|
| `columns` | list, 1 to 6 texts | yes | Column headers, each up to 30 characters. |
| `rows` | list, up to 50 rows | no | Each row is a list of cells: text (up to 80 characters) or number. At most as many cells as columns. Default empty. |
| `label` | text, up to 60 characters | no | Title of the card. |

- **Value:** the rows.
- **Size:** at least 3 columns wide, height 80 to 800.
- An empty table shows "No entries yet". Wide tables can be scrolled sideways.

```json
{
  "type": "table", "id": "bestellungen", "label": "Orders",
  "columns": ["No.", "Customer", "€"],
  "rows": [["1047", "Jonas M.", 89.9], ["1048", "Aylin S.", 34.5]]
}
```

## Unknown types

Packlets rejects a `type` that doesn't exist with `400 invalid_body`. TypeScript types you can copy are under [Ready-made code](https://packlets.app/en/docs/beispiele.md#types-for-typescript).
