> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celestia.rest/llms.txt
> Use this file to discover all available pages before exploring further.
# Container Scripts
> Complete reference for container scripting syntax
## Overview
Container scripts use a special syntax to create Components V2 containers — Discord's modern alternative to embeds. This page explains every property with real examples you can copy and use immediately.
This page is written so that even if you've never touched a container script before, you'll understand exactly what everything does. Every property has plain English explanations and working examples.
***
## Basic Structure
Every container must be wrapped in `{container}` tags:
```
{container}
$v{property: value}
{container}
```
**Components:**
* `{container}` — Opening tag
* `$v{property: value}` — Property declarations
* `{container}` — Closing tag
***
## Property Syntax
Sets the colored accent bar on the left side of the container.
**Syntax:**
```
$v{color: #hex}
```
**Examples:**
```
$v{color: #5865F2}
$v{color: #ff0000}
$v{color: {random.color}}
```
**Note:** Must be a hex color code starting with `#`. Use `{random.color}` for a different random color every time.
Blurs the entire container behind a spoiler. Users must click to reveal it.
**Syntax:**
```
$v{spoiler: true}
```
**Example:**
```
{container}
$v{spoiler: true}
$v{text: This is hidden until clicked!}
{container}
```
The most common property. Adds a block of text to your container. Supports full Discord markdown.
**Syntax:**
```
$v{text: your text here}
```
**Examples:**
```
$v{text: Hello world!}
$v{text: ## This is a big heading}
$v{text: **Bold** and *italic* and `code`}
$v{text: Welcome {user.mention}!}
$v{text: -# This is small subtext like a footer}
```
**Markdown support:**
* `## Heading` — Large heading
* `### Subheading` — Medium heading
* `**text**` — Bold
* `*text*` — Italic
* `` `text` `` — Inline code
* `-# text` — Small subtext (perfect for footers)
* `> text` — Quote block
* `~~text~~` — Strikethrough
* `[text](url)` — Clickable link
**Limits:** 4000 characters per text block
Adds a visual divider line or empty space between components. Helps organize your container into clear sections.
**Syntax:**
```
$v{separator: small}
$v{separator: large}
$v{separator: space}
```
**Types:**
* `small` — Thin horizontal line with small spacing
* `large` — Thin horizontal line with large spacing
* `space` — Empty gap with no line, just whitespace
**Example:**
```
{container}
$v{text: First section}
$v{separator: small}
$v{text: Second section}
$v{separator: large}
$v{text: Third section}
{container}
```
Puts text on the left with either a thumbnail image or a link button on the right. Perfect for profile cards and user info layouts.
**Syntax with thumbnail:**
```
$v{section: your text || thumbnail:image_url}
```
**Syntax with button:**
```
$v{section: your text || button:https://example.com}
```
**Multiple lines of text:**
```
$v{section: line one && line two && line three || thumbnail:image_url}
```
Use `&&` to separate multiple lines of text on the left side.
**Examples:**
```
$v{section: {user} || thumbnail:{user.avatar}}
$v{section: Click to visit our website || button:https://example.com}
$v{section: ## {user} && Joined {user.joined_at} || thumbnail:{user.avatar}}
$v{section: {guild.name} && {guild.count} members || thumbnail:{guild.icon}}
```
**Note:** A section must always have either `thumbnail:` or `button:` on the right side. A section with just text and nothing on the right will cause an error.
Displays one or more images in a grid layout, just like Discord's image grid when you send multiple photos.
**Syntax:**
```
$v{gallery: image_url}
$v{gallery: url1 && url2 && url3}
```
**Examples:**
```
$v{gallery: https://example.com/image.png}
$v{gallery: {user.avatar}}
$v{gallery: {guild.banner}}
$v{gallery: https://example.com/1.png && https://example.com/2.png}
```
**Grid layout by image count:**
* 1 image — Full width
* 2 images — Side by side
* 3 images — One large left, two stacked right
* 4 images — 2x2 grid
**Limits:** Maximum 10 images per gallery block
Adds clickable buttons to your container. Multiple consecutive button properties automatically group into the same row.
**Syntax:**
```
$v{button: label:Text && style:link && url:https://example.com}
```
**Button properties:**
* `label` — Button text (required)
* `style` — Button color: `link`, `primary`, `secondary`, `success`, `danger`
* `url` — URL to open (required for `link` style)
* `custom_id` — Custom ID for non-link buttons
* `emoji` — Emoji on the button
* `disabled:true` — Makes button unclickable
**Examples:**
```
$v{button: label:Website && style:link && url:https://example.com}
$v{button: label:Accept && style:success && custom_id:accept}
$v{button: label:Deny && style:danger && custom_id:deny}
$v{button: label:Click Me && style:primary && emoji:🎉}
```
**Button styles:**
* `link` — Opens a URL (requires `url`)
* `primary` — Blue/blurple
* `secondary` — Gray
* `success` — Green
* `danger` — Red
**Limits:** Maximum 5 buttons per row
***
## Complete Examples
```
{container}
$v{color: #5865F2}
$v{text: ## Welcome to {guild.name}!}
$v{separator: small}
$v{text: Hey {user.mention}, glad you're here!}
$v{text: -# Joined {time}}
{container}
```
```
{container}
$v{color: {random.color}}
$v{section: ## {user} || thumbnail:{user.avatar}}
$v{separator: small}
$v{text: **Joined:** {user.joined_at_timestamp}}
$v{text: **Top Role:** {user.top_role}}
$v{text: **Position:** {user.join_position_suffix} to join}
{container}
```
```
{container}
$v{color: #ff73fa}
$v{section: ## {user} just boosted! || thumbnail:{user.avatar}}
$v{separator: small}
$v{text: thank you for boosting {guild.name}!}
$v{text: We now have {guild.boost_count} boosts - Tier {guild.boost_tier}}
$v{separator: small}
$v{text: -# {timestamp}}
{container}
```
```
{container}
$v{color: #5865F2}
$v{section: ## {guild.name} || thumbnail:{guild.icon}}
$v{separator: small}
$v{text: **Members:** {guild.count}}
$v{text: **Boosts:** {guild.boost_count} (Tier {guild.boost_tier})}
$v{text: **Owner:** {guild.owner_mention}}
$v{text: **Created:** {guild.created_at}}
$v{separator: small}
$v{gallery: {guild.banner}}
{container}
```
```
{container}
$v{color: #ff0000}
$v{text: ## Announcement}
$v{separator: small}
$v{text: Your announcement text here. Supports bold, italic, and more.}
$v{gallery: https://example.com/banner.png}
$v{separator: small}
$v{button: label:Read More && style:link && url:https://example.com}
$v{text: -# Posted {time} by {user}}
{container}
```
```
{container}
$v{color: #5865F2}
$v{text: ## Our Links}
$v{separator: small}
$v{text: Everything you need in one place.}
$v{separator: small}
$v{button: label:Website && style:link && url:https://example.com}
$v{button: label:Support Server && style:link && url:https://discord.gg/example}
$v{button: label:Documentation && style:link && url:https://docs.example.com}
{container}
```
***
## Tips & Best Practices
**Making a footer**
Containers don't have a built-in footer property. Use `-#` at the start of a text block instead — it renders as small gray subtext, exactly like a footer:
```
$v{text: -# Sent by {user} • {time}}
```
**Making a title**
No built-in title property either. Use markdown headings inside a text block:
```
$v{text: ## Big Title}
$v{text: ### Smaller Subtitle}
```
**Common Mistakes**
* Forgetting the closing `{container}` tag
* Using `section` without a `thumbnail:` or `button:` accessory on the right side
* Using image URLs that aren't direct image links in galleries
* Putting more than 5 buttons consecutively in one row
* Not starting hex colors with `#`
**Variable Support**
All property values support dynamic placeholders. See the [Variables guide](/variables) for the complete list of available variables like `{user.mention}`, `{guild.name}`, `{timestamp}`, etc.
***
## Character Limits
| Property | Limit |
| --------------- | --------------- |
| Text block | 4000 characters |
| Gallery images | 10 max |
| Buttons per row | 5 max |
***
## Syntax Reference
**Property Format:**
```
$v{property: value}
```
**Section Format:**
```
$v{section: text || thumbnail:url}
$v{section: text || button:url}
```
**Gallery Format:**
```
$v{gallery: url1 && url2 && url3}
```
**Button Format:**
```
$v{button: label:Text && style:link && url:https://...}
```
***
## Related Resources
Complete list of available variables
Full container builder command guide
Embed scripting syntax reference
Send containers through webhooks