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

# Layout

> The pieces of a message written where the message is: rows, link buttons, texts, sections, galleries, files, separators and containers

The `components` of a message take pieces made by ChapterJS: your buttons, menus and forms, and the helpers of this page, imported from `'chapterjs'`. Each is checked against the limits of Discord when it is made.

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { container, separator, text, type GuildMember, type TextChannel } from 'chapterjs';

async function profile(channel: TextChannel, member: GuildMember) {
  await channel.send({
    components: [container([text(`## ${member.displayName}`), separator(), text(`${member.roles.length} roles`)], { color: 0xc026d3 })],
  });
}
```

> [!NOTE]
>
> How to build a message out of these is in [Embeds and layout](https://www.chapterjs.org/components/embeds.md).

## Helpers

### row()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
row(components: readonly (ButtonComponent | SelectComponent)[]): ActionRowComponent
```

A row of components: up to 5 buttons, or one select menu. The framework makes rows by itself; use this to choose which buttons share a row.

[Discord documentation](https://docs.discord.com/developers/components/reference#action-row)

### linkButton()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
linkButton(options: LinkButtonOptions): ButtonComponent
```

A button that opens a link. Nothing runs in your bot when it is clicked: Discord opens the address.

[Discord documentation](https://docs.discord.com/developers/components/reference#button)

### premiumButton()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
premiumButton(skuId: Snowflake, options?: { disabled?: boolean }): ButtonComponent
```

A button that offers something to buy: Discord shows the name and the price of the SKU itself.

[Discord documentation](https://docs.discord.com/developers/components/reference#button)

### text()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
text(content: string): TextComponent
```

A text in a message built with components. Markdown works as in any message, mentions included. The texts of a message add up to 4000 characters at most.

[Discord documentation](https://docs.discord.com/developers/components/reference#text-display)

### section()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
section(texts: string | readonly string[], accessory: ButtonComponent | ThumbnailComponent): SectionComponent
```

One to three texts with a button or a thumbnail beside them.

[Discord documentation](https://docs.discord.com/developers/components/reference#section)

### thumbnail()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
thumbnail(media: string | MediaOptions): ThumbnailComponent
```

A small picture beside the texts of a section.

[Discord documentation](https://docs.discord.com/developers/components/reference#thumbnail)

### gallery()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
gallery(items: readonly (string | MediaOptions)[]): GalleryComponent
```

Up to 10 pictures or videos, shown in a grid.

[Discord documentation](https://docs.discord.com/developers/components/reference#media-gallery)

### file()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
file(name: string, options?: { spoiler?: boolean }): FileComponent
```

A file sent with the message (its `files`), shown where it is placed.

[Discord documentation](https://docs.discord.com/developers/components/reference#file)

### separator()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
separator(options?: SeparatorOptions): SeparatorComponent
```

Space between two pieces, with a line by default.

[Discord documentation](https://docs.discord.com/developers/components/reference#separator)

### container()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
container(children: readonly ContainerChild[], options?: ContainerOptions): ContainerComponent
```

A box around texts, sections, rows, galleries, files and separators, with an optional color on its left, like an embed.

[Discord documentation](https://docs.discord.com/developers/components/reference#container)

## Options

### LinkButtonOptions

A link button: what it shows, and the address it opens.

**url** `string` *required*

The address the button opens (512 characters at most).

**label** `string`

The text on the button (80 characters at most).

**emoji** `EmojiInput`

An emoji on the button, before the label.

**disabled** `boolean`

Shows the button greyed out, impossible to click.

### MediaOptions

A picture or a video: its address, or `attachment://name` for a file of the message.

**url** `string` *required*

The address of the media: a link, or `attachment://chart.png` for a file sent with the message.

**description** `string`

What the media shows, for people who can't see it (1024 characters at most).

**spoiler** `boolean`

Blurs the media until it is clicked.

### SeparatorOptions

How a separator looks.

**divider** `boolean`

Shows a line. Shown by default.

**spacing** `'small' | 'large'`

How much space: `'small'` (the default) or `'large'`.

### ContainerOptions

How a container looks.

**color** `number`

The color of the line on its left, as a number (`0xc026d3`).

**spoiler** `boolean`

Blurs the whole container until it is clicked.

## The pieces

### MessageComponent

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type MessageComponent = ContainerChild | ContainerComponent
```

What the `components` of a message take. Buttons and menus are put in rows by the framework (5 buttons per row, a menu alone in its row); `row()` is there to choose. Such a message holds 5 rows at most. As soon as a message has a text, a section, a gallery, a file, a separator or a container, it is built with components only: Discord then takes no `content` and no `embeds`.

### ContainerChild

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ContainerChild = ButtonComponent | SelectComponent | ActionRowComponent | TextComponent | SectionComponent | GalleryComponent | FileComponent | SeparatorComponent
```

What a container can hold.

### Piece

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
interface Piece<Kind extends string> { readonly [brand]: Kind }
```

A piece of a message made by ChapterJS: a button, a menu, a layout. Only the framework makes pieces: a plain object is refused where a piece is expected, with a message that says what to use instead. Every piece is a `Piece`:

| Type | Made by |
| - | - |
| `ButtonComponent` | A button declared with `button()`, `linkButton()`, `premiumButton()` |
| `SelectComponent` | A select menu declared with `select()` |
| `ModalComponent` | A form declared with `modal()`, for `interaction.showModal()` |
| `ActionRowComponent` | `row()` |
| `TextComponent` | `text()` |
| `SectionComponent` | `section()` |
| `ThumbnailComponent` | `thumbnail()` |
| `GalleryComponent` | `gallery()` |
| `FileComponent` | `file()` |
| `SeparatorComponent` | `separator()` |
| `ContainerComponent` | `container()` |

[Discord documentation](https://docs.discord.com/developers/components/reference)


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