Skip to content

CreateEmbed

CreateEmbed creates Discord embed payloads using a chainable API. Per-field limits (title length, field count, URLs) are validated by each setter; the 6,000-character total is checked by toJSON().

import { CreateEmbed } from "lunibee";
// or from the sub-package:
import { CreateEmbed } from "@lunibee/builders";

All methods return this for chaining.

Sets the embed title (max 256 characters).

embed.setTitle("Server Status 🐝");

Sets the embed description (max 4096 characters).

embed.setDescription("All systems operational.");

Sets the embed accent color as a hex integer (0 to 0xFFFFFF; anything else throws a RangeError).

embed.setColor(0xf59e0b); // amber
embed.setColor(0x5865f2); // Discord blurple
embed.setColor(0xed4245); // red

Makes the title a hyperlink. Embed URLs (here and in the author, footer, thumbnail and image) must be valid and use http, https or attachment, or a TypeError is thrown.

embed.setURL("https://lunibee.js.org");

Adds a timestamp. Defaults to now if no date is passed.

embed.setTimestamp();
embed.setTimestamp(new Date("2024-01-01"));

Sets the embed author.

embed.setAuthor({
name: "Lunibee Bot",
icon_url: "https://example.com/icon.png",
url: "https://lunibee.js.org",
});

Sets the embed footer.

embed.setFooter({ text: "Powered by Lunibee 🐝", icon_url: "https://example.com/icon.png" });

Sets the thumbnail (small image on the top-right). Accepts a URL string or { url }.

embed.setThumbnail(user.displayAvatarURL({ size: 128 }));

Sets the large embed image. Accepts a URL string or { url }.

embed.setImage("https://example.com/banner.png");

Adds one or more fields (max 25 total, each name ≤ 256 chars, value ≤ 1024 chars). Also accepts a single array: addFields([a, b]).

embed.addFields(
{ name: "Ping", value: "24ms", inline: true },
{ name: "Uptime", value: "48h", inline: true },
{ name: "Guilds", value: "1,234", inline: true },
);

spliceFields(index, deleteCount, ...fields)

Section titled “spliceFields(index, deleteCount, ...fields)”

Replaces or removes fields at a given index.

Replaces all fields with the given array.

clearFields() / clearTitle() / clearDescription()

Section titled “clearFields() / clearTitle() / clearDescription()”

Remove the fields, title or description.

Getter returning the same deep-cloned payload as toJSON().

Serializes the embed to a raw Discord API-compatible object. Throws a RangeError when the title, description, footer text, author name and fields add up to more than 6,000 characters.

const payload = embed.toJSON();
// Use in: channel.send({ embeds: [embed] })
import { CreateEmbed } from "lunibee";
const embed = new CreateEmbed()
.setTitle("Moderation Log 🔨")
.setDescription("A member was banned from the server.")
.setColor(0xed4245)
.setAuthor({ name: "AutoMod", icon_url: "https://example.com/automod.png" })
.addFields(
{ name: "User", value: `<@${bannedUserId}>`, inline: true },
{ name: "Reason", value: banReason, inline: true },
{ name: "Moderator", value: `<@${modId}>`, inline: false },
)
.setTimestamp()
.setFooter({ text: "Lunibee Moderation" });
await logChannel.send({ embeds: [embed] });
Property Limit
Title 256 characters
Description 4,096 characters
Field name 256 characters
Field value 1,024 characters
Fields 25
Footer text 2,048 characters
Author name 256 characters
Total embed characters 6,000

setTitle, setDescription, setURL, setThumbnail and setImage accept null to clear the field, so a value that may be missing needs no separate branch:

embed.setThumbnail(guild.iconURL()); // cleared when the guild has no icon