Adding a Panel or Panel Button
How to build a Components V2 panel that users click through, and how to add a button or select to an existing one. The text and layout rules are in Panel Prose and Layout; this page covers the wiring.
Choose the lifecycle
Section titled “Choose the lifecycle”First decide whether this should be a panel at all, and which kind, with Command Archetypes.
- Global route: the panel outlives the command, and every click rebuilds its state from the custom
ID plus the database. Most settings panels (
/config,/moderation,/memories) work this way. - Anchor workflow: a multi-step write that belongs to one command session, with a collector and a timeout. See Pattern 4A.
The rest of this page covers global routes. Do not move an existing collector to a global route unless the panel needs to outlive the command.
A panel named example has three files. Copy conditioning (small, with a modal write) or
moderation (categories, pagination, receipts):
| File | Owns |
|---|---|
src/utils/discord/examplePanelCatalog.ts | EXAMPLE_ROUTE_NAMESPACE, EXAMPLE_ROUTE_VERSION, the route union, its codecs, buildExampleRouteId(), and parseExamplePanelRoute() |
src/utils/discord/ui/examplePanel.ts | A pure builder from state to payload, ending in buildPanelContainer() |
src/utils/discord/interactions/exampleRoutes.ts | createExampleInteractionRoute(overrides) and the exported exampleInteractionRoute |
Then:
- Register
exampleInteractionRoutein theInteractionRouteRegistrylist insrc/utils/discord/interactions/router.ts. If the namespace differs from the command name, add it to the outdated-panel mapping in the same file, or a click on an old panel tells users to run a command that does not exist. - Send the first render from the command’s
execute()withdeliverGuardedPanel(interaction, payload, { method: "reply", locale, flags: payload.flags | MessageFlags.Ephemeral }), ordeferReply()first and usemethod: "editReply"when loading state is slow. - Add the builder to
tests/unit/discord/componentsV2ProducerManifest.test.ts, which fails for any module that setsMessageFlags.IsComponentsV2without an entry.
Custom IDs
Section titled “Custom IDs”Build every ID with the catalog’s builder, which calls buildInteractionRouteId(namespace, version, ...segments):
- IDs are
namespace:version:action:locale:...fields. Segments cannot be empty or contain:. - The builder throws past Discord’s 100 characters. Put a list index and a short content fingerprint in the ID; never a name, a URL, or free text.
- Carry the panel locale, so later clicks keep the language without another database read.
- Field order in a codec is a published format: posted messages still carry IDs from older builds. To change the order or meaning of a field, bump the version. The registry then answers old clicks with an outdated-panel reply instead of misreading them.
- For a write that depends on a list (remove the third entry), put a fingerprint of that list in the
ID and refuse the write when it no longer matches. See
computeConditioningAggregateFingerprint().
Handling a click
Section titled “Handling a click”const scope = await beginPanelInteraction(interaction, { authorize: () => isAuthorized(interaction), onDenied: () => interaction.editReply(terminalPayload(route.locale, "commands.example.permission_denied")), load: () => dependencies.resolveScope(interaction), onMissing: () => interaction.editReply(terminalPayload(route.locale, "commands.example.not_setup")),});if (!scope) return;await repaint(interaction, route.locale, scope);beginPanelInteraction()acknowledges first, then authorizes and loads. Discord allows three seconds for the acknowledgement, and anything slow before it loses the interaction.- A branch that opens a modal does not use it:
showModal()must be that interaction’s acknowledgement, so everything before it (permission check, one fast read) has to finish inside the three seconds. Refuse such a press (denied, stale, nothing to change) withreplyPanelReceipt(interaction, receipt)fromsrc/utils/discord/ui/panel.ts. It sends the receipt as a private card and never edits the panel that was pressed. Do not reply with plaincontent. - Check the interaction type for each action (
isButton(),isStringSelectMenu(),isModalSubmit()) and throw on a mismatch; the router logs it and replies with a generic error. - Repaint through
deliverGuardedPanel(interaction, payload, { locale, receipt }). It validates Discord’s limits, substitutes a fallback in production, and emits apanel_failuremetric for anerrororwarningreceipt. Return the failure as a receipt; do not throw after a write has committed. See Panel failure observability. - Take repositories and other side effects as dependencies of
createExampleInteractionRoute(), so tests pass fakes instead of usingmock.module(). - After a successful write, call
recordPanelActionStat()with an action fromPANEL_ACTIONSinsrc/constants/panelActions.ts(<surface>.<scope>.<resource>.<verb>). Add the action there first; the metric only accepts listed identifiers.
Opening on a page
Section titled “Opening on a page”A panel with categories takes an optional page option so users can jump straight to a page or
category; Command Archetypes says which
panels get one. The helpers are in src/utils/discord/autocomplete/panelPageAutocomplete.ts:
- Write
listExamplePageDestinations(locale, context)next to the command’s executor. It returns onePanelPageDestinationper page the invoker may open, filtered by the same visibility rules the page select uses, with the existing category and page label keys. A category without pages is one destination with a nullpageandpageLabel, as in/memories. - Add the option with
configurePanelPageOption(option, description)and the keycommands.<path>.page_description. Keep it optional: a subcommand or a required option stops the bare command from running. - In
autocomplete, answer withrespondWithPanelPages(interaction, destinations). Labels readCategory > Pageand match on either half. Autocomplete has the three-second limit and no deferral, so build the context from the interaction (guild, member permissions) instead of a database read. If the command has another autocompleted option, branch oninteraction.options.getFocused(true).name. - In
execute, runresolvePanelPage(destinations, submitted)on destinations rebuilt from the loaded scope; a suggestion does not authorize anything. Open the panel on the result through the normal repaint so each page loads its own data. When nothing matches, open the default page withpanelPageNotFoundReceipt(locale).
A panel whose pages belong to a persona also takes an optional option named persona, so the loader
localizes commands.<path>.persona_description. Check that key is free first, because the loader applies
whatever text it already holds. Answer it with handleWorkspacePersonaAutocomplete
and resolve it with resolveSelectedPersona from src/utils/persona/personaOptionValue.ts, which also
accepts a typed nickname that exactly one persona has. When nothing resolves, open on the default
persona with panelPersonaNotFoundReceipt(locale). A command that deletes without a confirmation step
accepts only a picked ID, as /persona remove does.
Discord limits
Section titled “Discord limits”validateComponentsV2MessageLimits() in src/utils/discord/ui/componentsV2Limits.ts enforces these,
and deliverGuardedPanel() runs it:
- 40 components per message, counting every nested component. Modal components do not count, so a long form belongs in a modal.
- 4,000 characters across all
TextDisplaycomponents. Bound body text withbuildTextPreview(), and render a stored prompt or note withrenderFencedPreview(). - 25 options per select, each value unique. A duplicate value makes Discord reject the payload, and no static check catches it.
Adding a button or select to an existing panel
Section titled “Adding a button or select to an existing panel”- Add the action to the route union and codecs in the catalog. Append fields; bump the version if an existing action’s fields change.
- Render the component in the
ui/builder with an ID from the catalog builder. Follow the colour and label rules in Panel Prose and Layout;tests/unit/discord/panelButtonColour.test.tschecks the styles. - Handle the action in the route file, with its interaction-type check.
- Add the
PANEL_ACTIONSentry if it writes, and localized labels under the panel’s key prefix insrc/locales/en-US/. - Extend the panel’s route test and its
*PanelLimits.test.ts, then check that the extra component stays under 40 in the fullest state.
tests/unit/discord/exampleRoutes.test.ts: each action with fake dependencies, including denied, missing, stale fingerprint, and write failure.tests/unit/discord/examplePanelLimits.test.ts: the builder across every locale insrc/locales/, receipts on and off, each state, list sizes around the page size, and varied content shapes (long bodies, backticks, empty values). Uniform short fixtures miss the overflows.- A table of literal custom IDs when the panel has several versions in use, as
WIRE_CONTRACT_V2intests/unit/discord/personalConfigRoutes.test.tsdoes.
Run bun run check, bun run lint, bun run check-locales, and bun run test, then click through
the panel in Discord in a second locale.
Background: Command System, Message Components V2, Modal Input Components.