Modals Overview

What are modals in Spraxium

Modals are overlay forms that Discord presents to users when triggered by a button click, select menu interaction, or application command. They collect structured input through fields like text inputs, select menus, radio groups, and checkboxes. In Spraxium, modals follow the same declarative decorator-handler pattern used by buttons and selects, but with a richer field system, built-in validation, dynamic fields, and per-user caching that warrants a dedicated documentation category.

The modal system consists of two main pieces: a @ModalComponent class that declares the modal's structure (title, fields, and options), and a @ModalHandler class that processes the submitted values. The ModalService renders the component into a Discord-ready modal object, and the ModalDispatcher routes submissions to the correct handler after running validation rules.

Unlike buttons and selects where the component is a lightweight decorator on a class, modals use property-level decorators to define each field. This gives you fine-grained control over field types, placeholder text, validation constraints, conditional inclusion, and dynamic generation, all expressed through TypeScript decorators.

When a modal is the right choice

Use a modal when the user needs to type or review multiple pieces of information before submitting. Feedback forms, ticket creation, profile setup, application flows, and admin input screens are the usual fit.

If the user only needs to pick one option or click a confirmation, a button or select menu is usually simpler. A modal is most helpful when the interaction needs structured text input and a clear submission boundary.

Defining a modal component

Use @ModalComponent to mark a class as a modal definition. The decorator accepts an object with id (the customId that Discord sends back on submission) and title (displayed at the top of the modal). Field decorators on the class properties define the modal's input fields.

import { ModalComponent, ModalInput } from '@spraxium/components';

@ModalComponent({ id: 'feedback-modal', title: 'Send Feedback' })
export class FeedbackModal {
  @ModalInput({
    label: 'Subject',
    placeholder: 'Brief summary of your feedback',
    required: true,
    minLength: 3,
    maxLength: 100,
    style: 'short',
  })
  subject!: string;

  @ModalInput({
    label: 'Details',
    placeholder: 'Describe your feedback in detail...',
    required: true,
    minLength: 10,
    maxLength: 4000,
    style: 'paragraph',
  })
  details!: string;
}

Creating a modal handler

The @ModalHandler decorator links a handler class to a specific modal component. The handler's handle method receives the modal submission and any injected parameters. Use tagged field decorators to extract individual field values by their property name. The generic @ModalField(fieldId) works for every field type; the nine typed variants (@ModalTextField, @ModalStringSelectField, @ModalRadioGroupField, etc.) make the intent explicit and are preferred when the field type is known at compile time.

import { Ctx } from '@spraxium/common';
import { ModalHandler, ModalTextField, type ModalContext } from '@spraxium/components';
import { FeedbackModal } from './feedback.modal';

@ModalHandler(FeedbackModal)
export class FeedbackModalHandler {
  async handle(
    @ModalTextField('subject') subject: string,
    @ModalTextField('details') details: string,
    @Ctx() ctx: ModalContext,
  ): Promise<void> {
    await ctx.reply({
      content: `Thank you for your feedback on '${subject}'.`,
      flags: 'Ephemeral',
    });
  }
}

For full documentation on all field decorators, guard integration, and the complete injection API, see Handlers and Field Injection.

Showing a modal

Use ModalService to build a Discord-ready modal and present it to the user. The build method takes the modal component class and returns a modal interaction response. You typically call this from a button handler, select handler, or slash command that has received an interaction with a showModal method.

import { ButtonHandler, Ctx } from '@spraxium/components';
import { ModalService } from '@spraxium/components';
import type { ButtonInteraction } from 'discord.js';
import { OpenFeedbackButton } from './open-feedback.button';
import { FeedbackModal } from './feedback.modal';

@ButtonHandler(OpenFeedbackButton)
export class OpenFeedbackHandler {
  constructor(private readonly modals: ModalService) {}

  async handle(@Ctx() interaction: ButtonInteraction): Promise<void> {
    const modal = this.modals.build(FeedbackModal);
    await interaction.showModal(modal);
  }
}

Handler field injection

The @ModalHandler handler class receives submitted field values through parameter decorators. Use typed decorators like @ModalTextField, @ModalStringSelectField, and @ModalCheckboxField to inject each field value directly into the handle() method, with no manual interaction object parsing needed.

@ModalHandler(FeedbackModal)
export class FeedbackHandler {
  async handle(
    @ModalTextField('subject') subject: string,
    @ModalTextField('message') message: string,
    @Ctx() ctx: ModalContext,
  ): Promise<void> {
    await ctx.reply({ content: `Received: ${subject}`, flags: 'Ephemeral' });
  }
}

The old @Field decorator is deprecated in the current API in favor of the typed variants. For the full list of typed field decorators and their resolved TypeScript types, see Handlers and Field Injection.

ModalService API reference

The most common pair is build for a first render and buildFor for flows where you want user-aware prefilling after a validation failure. In other words, build is the simple path; buildFor is the ergonomic path for retry-heavy form flows.

Module registration

Register your modal handlers in the handlers array of a feature module. Modal component classes decorated with @ModalComponent and button classes decorated with @Button are metadata-only and are never registered in any module. The system scans all registered handler instances for @ModalHandler metadata during the boot lifecycle and reads the referenced modal component's metadata by class reference.

import { Module } from '@spraxium/core';
import { FeedbackModalHandler } from './feedback.handler';
import { OpenFeedbackHandler } from './open-feedback.handler';

@Module({
  handlers: [FeedbackModalHandler, OpenFeedbackHandler],
})
export class FeedbackModule {}

Dispatch flow

When a user submits a modal, the interaction goes through several stages before reaching your handler. Understanding this flow helps you reason about where validation, caching, and field resolution happen.

This layered flow is what keeps modal handlers small. Validation, caching, context loading, and field extraction happen before your business logic runs, so the handler can focus on the accepted submission instead of reconstructing the form state by hand.