Components Overview

What are components

The @spraxium/components package provides a decorator-driven system for building interactive Discord UI elements. Buttons, select menus, modals, and embeds are all defined as decorated classes, wired through metadata, and dispatched automatically when users interact with your bot. The package also includes a flow context system that threads stateful data across multi-step interactions without manual state management.

Unlike raw discord.js builders where you construct every object imperatively, Spraxium components use class decorators to declare what a component looks like, separate handler decorators to define what happens when a user interacts, and injectable services to render components at runtime. This separation keeps component definitions reusable, handlers testable, and rendering decoupled from business logic.

The package ships five component families: buttons (static, link, and dynamic), select menus (string, user, role, mentionable, channel), modals (with 11 field types, validation, and caching), embeds (declarative schema-driven), and v2 containers (composable layout blocks). Each family follows the same decorator-handler-service pattern, so learning one transfers directly to the others.

Plugin configuration

The module reads its configuration from a plugin entry produced by defineComponents. This factory accepts a ComponentsConfig object that controls context storage, error messages, and per-component behavior. Registration follows the same pattern as every Spraxium plugin: call the factory, add the result to the plugins array in spraxium.config.ts.

import { defineComponents } from '@spraxium/components';

export const componentsPlugin = defineComponents({
  context: {
    storage: 'memory',
    defaultTtl: 300,
  },
  errorMessages: {
    expired: 'This interaction has expired.',
    restricted: 'You are not allowed to use this component.',
  },
});

The context.storage field selects the persistence backend for flow contexts. Four adapters are available: 'memory' for development, 'filesystem' for single-instance bots, 'redis' for multi-instance deployments, and 'sqlite' for lightweight persistence. The defaultTtl sets the expiration in seconds for contexts that do not specify their own TTL.

The decorator-handler pattern

Every interactive component in Spraxium follows a two-class architecture: one class defines what the component looks like, and a separate class defines what happens when the user interacts with it. This separation exists because Discord components are rendered once but can be clicked many times by different users. Keeping the visual definition apart from the interaction logic makes components reusable across multiple messages and handlers independently testable.

The component class carries a decorator like @Button, @StringSelect, or @ModalComponent that stores metadata about appearance and identity. The handler class carries a corresponding decorator like @ButtonHandler, @StringSelectHandler, or @ModalHandler that references the component class. At runtime, the dispatcher reads both sets of metadata, matches incoming interactions to the correct handler, and invokes the handle method with injected parameters.

import { Button } from '@spraxium/components';

@Button({
  customId: 'confirm_action',
  label: 'Confirm',
  style: 'success',
})
export class ConfirmButton {}

Module wiring

The ComponentsModule is a global module that provides all component services (ButtonService, SelectService, ModalService, EmbedService, V2Service, ContextService). You do not import it directly. Add your handler classes to the handlers array of your feature module and the services become injectable automatically. Component classes decorated with @Button, @StringSelect, @ModalComponent, or @Embed are metadata-only and are never registered in any module.

import { Module } from '@spraxium/common';
import { ConfirmButtonHandler } from './components/confirm-btn.handler';

@Module({
  handlers: [ConfirmButtonHandler],
})
export class SettingsModule {}

Only the handler class goes in the handlers array. Component classes store their configuration as constructor-level metadata via Reflect.defineMetadata. The dispatcher reads that metadata directly from the class reference stored inside each handler's decorator, so no DI instantiation of component classes is ever needed.

Bootstrap lifecycle

Custom ID anatomy

Every interactive Discord component carries a customId string that identifies it when the user interacts. Spraxium uses a structured format to encode both the component identity and optional flow context into this string. The tilde character (~) separates the base ID from the context ID.

The splitCustomId helper parses these patterns internally. When a tilde is present, the dispatcher extracts the context ID, retrieves the SpraxiumContext from the configured storage adapter, checks expiration and user restrictions, and injects it via the @FlowContext parameter decorator.

Parameter injection

Handler handle methods receive their arguments through parameter decorators. The dispatcher resolves each parameter at invocation time based on the decorator metadata attached to the method signature. This system is consistent across all component types, so the same decorators work in button handlers, select handlers, and modal handlers.

Rendering components

Each component family has an injectable service that reads decorator metadata and produces discord.js builder objects. You inject the service into your command handlers, listeners, or other services and call its build method to produce action rows ready for message replies.

import { Ctx, SlashCommandHandler } from '@spraxium/common';
import { ButtonService, ContextService } from '@spraxium/components';
import type { ChatInputCommandInteraction } from 'discord.js';
import { ConfirmButton } from '../components/confirm-btn.component';
import { CancelButton } from '../components/cancel-btn.component';
import { SettingsCommand } from './settings.command';

@SlashCommandHandler(SettingsCommand)
export class SettingsCommandHandler {
  constructor(
    private readonly buttons: ButtonService,
    private readonly context: ContextService,
  ) {}

  async handle(@Ctx() interaction: ChatInputCommandInteraction): Promise<void> {
    const ctx = await this.context.create({ guildId: interaction.guildId });
    const row = this.buttons.rowWithContext(ctx, ConfirmButton, CancelButton);

    await interaction.reply({
      content: 'Are you sure you want to reset settings?',
      components: [row],
    });
  }
}

The build method accepts one or more component classes and returns an ActionRowBuilder. The rowWithContext variant attaches a context ID to every button in the row. For select menus, SelectService.build handles both static and dynamic options. For modals, ModalService.build constructs the full modal from schema metadata.

Shared concepts across families

Several architectural patterns recur across buttons, selects, modals, and embeds. Understanding these shared concepts once means you can apply them to any component type without relearning the fundamentals. The decorator-handler separation, metadata-driven rendering, context threading, and parameter injection all work identically regardless of the component family.

The documentation in this category covers buttons, selects, embeds, and the context system in detail. Modals have their own dedicated category because their field system, validation pipeline, caching mechanism, and dynamic schema building introduce concepts that are unique to form-like interactions and warrant deeper coverage.