Toju/docs-site/docs/plugin-development/api/ui.md

sidebar_position

sidebar_position
11

UI API

The UI API lets plugins add pages, settings pages, side panels, channel sections, actions, embed renderers, and controlled DOM mounts.

Prefer registered UI contributions over direct DOM mounting. Contribution APIs let Angular render the plugin UI when the matching app surface exists. Direct DOM mounting runs immediately and throws if the target selector is not present.

Required Capabilities

Method	Capability
ui.registerAppPage(id, contribution)	ui.pages
ui.registerSettingsPage(id, contribution)	ui.settings
ui.registerSidePanel(id, contribution)	ui.sidePanel
ui.registerChannelSection(id, contribution)	ui.channelsSection
ui.registerComposerAction(id, contribution)	ui.pages
ui.registerProfileAction(id, contribution)	ui.pages
ui.registerToolbarAction(id, contribution)	ui.pages
ui.registerEmbedRenderer(id, contribution)	ui.embeds
ui.mountElement(id, request)	ui.dom

Every registration returns a disposable. Push it into context.subscriptions.

App Page

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerAppPage('dashboard', {
    label: 'Raid Dashboard',
    path: '/plugins/example.raid-helper/dashboard',
    render: () => {
      const root = document.createElement('section');
      root.innerHTML = '<h1>Raid Dashboard</h1><p>Tonight: dungeon practice.</p>';
      return root;
    }
  }));
}

The page is hosted by /plugins/:pluginId/:pageId.

Settings Page

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerSettingsPage('preferences', {
    label: 'Raid Helper',
    settingsKey: 'raid-helper',
    order: 20,
    render: () => {
      const wrapper = document.createElement('section');
      const label = document.createElement('label');
      const checkbox = document.createElement('input');

      checkbox.type = 'checkbox';
      checkbox.checked = true;
      label.append(checkbox, ' Enable ready-check reminders');
      wrapper.append(label);
      return wrapper;
    }
  }));
}

Side Panel

Use ui.registerSidePanel for content that belongs in the server sidebar plugin area. Do not mount directly into [data-testid="plugin-room-side-panel"]; that host is route-specific and may not exist during plugin activation.

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerSidePanel('soundboard', {
    label: 'Soundboard',
    order: 10,
    render: () => {
      const panel = document.createElement('div');
      const button = document.createElement('button');

      button.type = 'button';
      button.textContent = 'Play chime';
      button.onclick = () => context.api.media.playAudioClip({
        url: 'https://cdn.example.com/chime.wav',
        volume: 0.6
      });
      panel.append(button);
      return panel;
    }
  }));
}

Capabilities required: ui.sidePanel and media.playAudio.

Channel Section

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerChannelSection('events', {
    label: 'Event Rooms',
    type: 'custom',
    order: 50
  }));
}

Composer Action

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerComposerAction('insert-standup', {
    icon: 'ST',
    label: 'Insert standup prompt',
    run: (actionContext) => {
      context.api.messages.send(
        'Standup: yesterday I..., today I..., blocked by...',
        actionContext.textChannel?.id
      );
    }
  }));
}

Capabilities required: ui.pages and messages.send.

Profile Action

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerProfileAction('wave', {
    label: 'Wave',
    run: (actionContext) => {
      context.api.messages.send(`Waving at ${actionContext.user?.displayName ?? 'someone'}!`);
    }
  }));
}

Toolbar Action

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerToolbarAction('open-dashboard', {
    label: 'Raid Helper',
    run: () => {
      context.api.logger.info('Open the Raid Helper plugin page from /plugins/example.raid-helper/dashboard');
    }
  }));
}

Embed Renderer

export function activate(context) {
  context.subscriptions.push(context.api.ui.registerEmbedRenderer('raid-card', {
    embedType: 'raid.card',
    render: (payload) => {
      const card = document.createElement('article');
      const title = document.createElement('h3');
      const body = document.createElement('p');

      title.textContent = payload?.title ?? 'Raid';
      body.textContent = payload?.description ?? 'No description provided.';
      card.append(title, body);
      return card;
    }
  }));
}

Example message content for this embed:

toju:embed:raid.card:{"title":"Friday Raid","description":"Meet in Lobby at 20:00."}

DOM Mount

Use DOM mounting only when normal UI contribution points are not enough. ui.mountElement resolves its target immediately. If the target does not exist, plugin activation fails with Plugin mount target not found: <selector>.

Safe uses:

• Mounting a global overlay, badge, or modal into body during activation.
• Mounting into a route-specific element only after checking that element exists.

Avoid:

• Mounting sidebar content into [data-testid="plugin-room-side-panel"]. Use ui.registerSidePanel.
• Mounting chat content into app-chat-messages during activation without checking for the element.

export function activate(context) {
  const badge = document.createElement('div');
  badge.textContent = 'Raid helper active';
  badge.style.position = 'fixed';
  badge.style.right = '16px';
  badge.style.bottom = '16px';
  badge.style.padding = '8px 10px';
  badge.style.background = '#111827';
  badge.style.color = 'white';
  badge.style.borderRadius = '6px';

  context.subscriptions.push(context.api.ui.mountElement('active-badge', {
    target: 'body',
    position: 'beforeend',
    element: badge
  }));
}

Route-specific mount example with a guard:

export function activate(context) {
  const target = document.querySelector('app-chat-messages');

  if (!target) {
    context.api.logger.warn('Chat messages host is not rendered yet; skipping chat mount');
    return;
  }

  const banner = document.createElement('div');
  banner.textContent = 'Raid helper active in this chat.';

  context.subscriptions.push(context.api.ui.mountElement('chat-banner', {
    target,
    position: 'afterbegin',
    element: banner
  }));
}

The runtime tags plugin-owned DOM and removes it on unload, but plugins should still keep mounts minimal and accessible.