CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-discordjs--builders

Type-safe builders for Discord API payloads including slash commands, embeds, buttons, select menus, and message components

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

components-v2.mddocs/

Components v2

Discord Components v2 provide enhanced rich media and content display capabilities for messages. These newer component types support advanced layouts, media galleries, files, and improved text display.

ContainerBuilder

Primary container for organizing v2 components with accent colors and spoiler support.

class ContainerBuilder {
  readonly data: Partial<APIContainerComponent>;

  constructor(data?: Partial<APIContainerComponent>);
  
  setAccentColor(color?: RGBTuple | number): this;
  clearAccentColor(): this;
  addActionRowComponents(...components: RestOrArray<ActionRowBuilder<AnyComponentBuilder>>): this;
  addFileComponents(...components: RestOrArray<FileBuilder>): this;
  addMediaGalleryComponents(...components: RestOrArray<MediaGalleryBuilder>): this;
  addSectionComponents(...components: RestOrArray<SectionBuilder>): this;
  addSeparatorComponents(...components: RestOrArray<SeparatorBuilder>): this;
  addTextDisplayComponents(...components: RestOrArray<TextDisplayBuilder>): this;
  addThumbnailComponents(...components: RestOrArray<ThumbnailBuilder>): this;
  spliceComponents(index: number, deleteCount: number, ...components: RestOrArray<AnyComponentBuilder>): this;
  setSpoiler(spoiler?: boolean): this;
  
  toJSON(): APIContainerComponent;
}

Usage Example:

import { ContainerBuilder, TextDisplayBuilder, SeparatorBuilder } from "@discordjs/builders";

const container = new ContainerBuilder()
  .setAccentColor([255, 0, 0]) // Red accent
  .addTextDisplayComponents(
    new TextDisplayBuilder()
      .setText("Welcome to the server!")
      .setTextStyle(TextDisplayStyle.Heading1)
  )
  .addSeparatorComponents(
    new SeparatorBuilder()
  )
  .setSpoiler(false);

FileBuilder

Builder for file display components.

class FileBuilder {
  readonly data: Partial<APIFileComponent>;

  constructor(data?: Partial<APIFileComponent>);
  
  setId(id: number): this;
  clearId(): this;
  
  toJSON(): APIFileComponent;
}

MediaGalleryBuilder

Builder for media gallery components that can contain multiple media items.

class MediaGalleryBuilder {
  readonly data: Partial<APIMediaGalleryComponent>;

  constructor(data?: Partial<APIMediaGalleryComponent>);
  
  addItems(...items: RestOrArray<MediaGalleryItemBuilder>): this;
  setItems(...items: RestOrArray<MediaGalleryItemBuilder>): this;
  spliceItems(index: number, deleteCount: number, ...items: RestOrArray<MediaGalleryItemBuilder>): this;
  setId(id: number): this;
  clearId(): this;
  
  toJSON(): APIMediaGalleryComponent;
}

MediaGalleryItemBuilder

Builder for individual items within a media gallery.

class MediaGalleryItemBuilder {
  readonly data: Partial<APIMediaGalleryItemComponent>;

  constructor(data?: Partial<APIMediaGalleryItemComponent>);
  
  setMediaURL(url: string): this;
  setAltText(altText: string): this;
  setSpoiler(spoiler?: boolean): this;
  setId(id: number): this;
  clearId(): this;
  
  toJSON(): APIMediaGalleryItemComponent;
}

Usage Example:

import { MediaGalleryBuilder, MediaGalleryItemBuilder } from "@discordjs/builders";

const gallery = new MediaGalleryBuilder()
  .addItems(
    new MediaGalleryItemBuilder()
      .setMediaURL("https://example.com/image1.jpg")
      .setAltText("First image"),
    new MediaGalleryItemBuilder()
      .setMediaURL("https://example.com/image2.jpg")
      .setAltText("Second image")
      .setSpoiler(true)
  );

SectionBuilder

Builder for section components that group related content.

class SectionBuilder {
  readonly data: Partial<APISectionComponent>;

  constructor(data?: Partial<APISectionComponent>);
  
  setId(id: number): this;
  clearId(): this;
  
  toJSON(): APISectionComponent;
}

SeparatorBuilder

Builder for separator components that create visual breaks.

class SeparatorBuilder {
  readonly data: Partial<APISeparatorComponent>;

  constructor(data?: Partial<APISeparatorComponent>);
  
  setId(id: number): this;
  clearId(): this;
  
  toJSON(): APISeparatorComponent;
}

TextDisplayBuilder

Builder for enhanced text display components with styling options.

class TextDisplayBuilder {
  readonly data: Partial<APITextDisplayComponent>;

  constructor(data?: Partial<APITextDisplayComponent>);
  
  setText(text: string): this;
  setTextStyle(style: TextDisplayStyle): this;
  setId(id: number): this;
  clearId(): this;
  
  toJSON(): APITextDisplayComponent;
}

Usage Example:

import { TextDisplayBuilder, TextDisplayStyle } from "@discordjs/builders";

const textDisplay = new TextDisplayBuilder()
  .setText("Important Announcement")
  .setTextStyle(TextDisplayStyle.Heading1);

ThumbnailBuilder

Builder for thumbnail components.

class ThumbnailBuilder {
  readonly data: Partial<APIThumbnailComponent>;

  constructor(data?: Partial<APIThumbnailComponent>);
  
  setURL(url: string): this;
  setId(id: number): this;
  clearId(): this;
  
  toJSON(): APIThumbnailComponent;
}

Types

type ContainerComponentBuilder = 
  | ActionRowBuilder<AnyComponentBuilder>
  | FileBuilder
  | MediaGalleryBuilder
  | SectionBuilder
  | SeparatorBuilder
  | TextDisplayBuilder
  | ThumbnailBuilder;

enum TextDisplayStyle {
  Body = 0,
  Heading1 = 1,
  Heading2 = 2,
  Heading3 = 3
}

Base ComponentBuilder Pattern

All v2 component builders inherit from ComponentBuilder<DataType> providing:

  • setId(id: number): this - Set a unique identifier for the component
  • clearId(): this - Remove the identifier
  • toJSON(): APIComponentType - Serialize to Discord API format

The ID system allows for referencing and updating specific components programmatically.

Install with Tessl CLI

npx tessl i tessl/npm-discordjs--builders

docs

assertions.md

components-v2.md

context-menu-commands.md

embeds.md

index.md

message-components.md

modals.md

select-menus.md

slash-commands.md

utilities.md

tile.json