Skip to content

Components V2 Builders

Lunibee includes builders for Discord’s Components V2 layout system, which provides richer message layouts with sections, galleries, separators, and more.

[!IMPORTANT] Components V2 requires the IS_COMPONENTS_V2 message flag. Messages using V2 components cannot also contain embeds or regular content.

import {
CreateContainer,
CreateSection,
CreateTextDisplay,
CreateMediaGallery,
CreateFileComponent,
CreateSeparator,
CreateThumbnail,
} from "lunibee";

The top-level V2 component that wraps other components. Set IS_COMPONENTS_V2 flag when sending.

Method Description
addComponents(...components) Adds child components (throws a TypeError when called with none).
setAccentColor(color) Sets the accent colour, an integer from 0 to 0xFFFFFF (anything else throws a RangeError).
setSpoiler(spoiler?) Marks the whole container as a spoiler (spoiler defaults to true).
const container = new CreateContainer()
.addComponents(
new CreateSection()
.addComponents(new CreateTextDisplay().setContent("**Welcome!** 🐝"))
.setAccessory(new CreateThumbnail().setUrl("https://example.com/bee.png")),
new CreateSeparator(),
new CreateTextDisplay().setContent("Explore the channels below."),
);
await channel.send({
components: [container],
flags: 1 << 15, // IS_COMPONENTS_V2
});

A two-column layout with text on the left and an optional accessory (thumbnail or button) on the right.

Method Description
addComponents(...textDisplays) Adds CreateTextDisplays to the left column.
setAccessory(accessory) Sets a CreateThumbnail or CreateButton accessory on the right.
const section = new CreateSection()
.addComponents(new CreateTextDisplay().setContent("**Lunibee v0.2.2** is here!"))
.setAccessory(
new CreateThumbnail()
.setUrl("https://example.com/release.png")
.setDescription("Release banner"),
);

Renders markdown text in a V2 layout.

Method Description
setContent(text) Sets the markdown text content (1-4000 characters).
const text = new CreateTextDisplay().setContent(
`## Server Stats\n- Members: **1,234**\n- Online: **456**`
);

Displays a grid of images.

Method Description
addItems(...items) Adds media items (at most 10 per gallery). Each item: { url, description?, spoiler? }.
const gallery = new CreateMediaGallery().addItems(
{ url: "https://example.com/img1.png", description: "Screenshot 1" },
{ url: "https://example.com/img2.png", description: "Screenshot 2" },
);

A small image accessory used in CreateSection.

Method Description
setUrl(url) Sets the image URL.
setDescription(text) Sets alt text for accessibility (max 1024 characters).
setSpoiler(spoiler?) Marks as a spoiler image (spoiler defaults to true).
const thumb = new CreateThumbnail()
.setUrl("https://example.com/avatar.png")
.setDescription("User avatar");

Renders a visual divider between components.

Method Description
setSpacing(spacing) Sets the spacing size (1 = small, 2 = large).
setDivider(show?) Whether to show a visible line (show defaults to true).
const sep = new CreateSeparator().setSpacing(2);

Attaches an uploaded file component to the layout.

Method Description
setUrl(url) Sets the attachment URL (attachment://filename, max 2048 characters). Required: toJSON() throws without it.
setSpoiler(spoiler?) Marks as spoiler (spoiler defaults to true).
const file = new CreateFileComponent().setUrl("attachment://report.pdf");

import {
CreateContainer,
CreateSection,
CreateTextDisplay,
CreateMediaGallery,
CreateSeparator,
CreateThumbnail,
CreateButton,
ButtonType,
CreateActionRow,
} from "lunibee";
const layout = new CreateContainer().addComponents(
// Header section
new CreateSection()
.addComponents(new CreateTextDisplay().setContent("## 🐝 Release Notes — v0.2.2"))
.setAccessory(new CreateThumbnail().setUrl("https://example.com/bee.png")),
new CreateSeparator().setSpacing(1),
// Body text
new CreateTextDisplay().setContent(
"This release includes bug fixes, new builders, and improved documentation.\n\n" +
"- Fixed duplicate `delete` in managers\n" +
"- Added DTS build exclusions\n" +
"- New `lunibee init` command"
),
new CreateSeparator(),
// Screenshots
new CreateMediaGallery().addItems(
{ url: "https://example.com/screenshot1.png", description: "New CLI output" },
{ url: "https://example.com/screenshot2.png", description: "Docs preview" },
),
);
await channel.send({
components: [layout],
flags: 1 << 15, // IS_COMPONENTS_V2
});

Builds a Components V2 message payload: the components’ JSON plus the IsComponentsV2 flag Discord requires. options adds other message fields; their flags are combined with the V2 flag (for example 64 for ephemeral). A V2 message cannot also carry content or embeds.

import { componentsV2Message, CreateContainer, CreateTextDisplay } from "lunibee";
await channel.send(componentsV2Message(
new CreateContainer().setAccentColor(0x57f287).addComponents(new CreateTextDisplay().setContent("## Settings")),
{ allowed_mentions: { parse: [] } },
));

Shows an entry from Discord’s content inventory (type ContentInventoryEntry). setId(id) sets the entry id; toJSON() returns { type, id }.

new CreateContentInventoryEntry().setId("123456");