Custom Shell Action Buttons

The yuuvis shell wraps your application in a standard layout that includes a sidebar. The sidebar contains the navigation entries for your registered shell apps. Below the app navigation, there is a dedicated actions area that hosts a configurable set of icon buttons — these are the shell action buttons.

On desktop, shell action buttons appear as icon buttons stacked vertically in the actions area at the bottom of the sidebar. On mobile and small screens, they appear as menu items inside a dropdown menu in the shell header.

Unlike registered shell apps, action buttons do not create a navigation entry or a route. They are suited for lightweight global actions such as opening a help link, launching a feedback dialog, or triggering any other application-wide behavior that does not require its own page.

Custom action buttons are registered at application startup through the provideShellActionButtons() function exported from @yuuvis/client-shell. Each button requires:

• A Material icon name (a string matching a Material Design icon, e.g. 'help', 'feedback')
• An onClick callback — called when the user clicks the button; receives a ShellActionButtonConfigAPI object with access to the Angular Router and the shell’s ConfigService
• An optional tooltip — an i18n translation key shown as a tooltip on desktop and as a label in the mobile menu

Prerequisites

• A working yuuvis shell client project (see Quick Start)
• @yuuvis/client-shell installed as a dependency
• Basic familiarity with Angular standalone application configuration (app.config.ts)

Registering Action Buttons

Call provideShellActionButtons() inside the providers array of your ApplicationConfig. The function accepts an array of ShellActionButton objects and registers them with the shell’s sidebar via dependency injection.

src/app/app.config.ts

import { ApplicationConfig } from '@angular/core';
import { provideShellActionButtons, ShellActionButtonConfigAPI } from '@yuuvis/client-shell';

export const appConfig: ApplicationConfig = {
  providers: [
    // ... other providers
    provideShellActionButtons([
      {
        iconName: 'help',
        tooltip: 'my.app.action-button.help.tooltip',
        onClick: (api: ShellActionButtonConfigAPI) => {
          const link = api.config.get('support')?.link;
          if (link) {
            window.open(link, '_blank');
          }
        }
      }
    ])
  ]
};

api.config is the shell’s ConfigService. api.config.get('support') reads the support key from the shell’s runtime configuration — the tooltip value 'my.app.action-button.help.tooltip' is an i18n key, while the config key 'support' retrieves runtime data. Replace both with values appropriate for your application.

The shell renders buttons top-to-bottom in the order they appear in the array. If provideShellActionButtons() is not called, no action buttons are shown.

The ShellActionButton Interface

Each entry in the array passed to provideShellActionButtons() must conform to the ShellActionButton interface:

export interface ShellActionButton {
  iconName: string;
  onClick: (api: ShellActionButtonConfigAPI) => void;
  tooltip?: string;
}

Property	Type	Required	Description
iconName	string	Yes	Any valid Material Design icon name. The icon is rendered via <mat-icon>. Examples: 'help', 'info', 'feedback'.
onClick	(api: ShellActionButtonConfigAPI) => void	Yes	Callback invoked when the user clicks the button. Receives a ShellActionButtonConfigAPI object.
tooltip	string	No	An i18n translation key. On desktop, rendered as a tooltip via matTooltip. On mobile, rendered as a text label next to the icon in the menu.

Both ShellActionButton and ShellActionButtonConfigAPI are exported from @yuuvis/client-shell.

The ShellActionButtonConfigAPI

The onClick callback receives a ShellActionButtonConfigAPI object:

export interface ShellActionButtonConfigAPI {
  router: Router;
  config: ConfigService;
}

Property	Type	Description
router	Router from @angular/router	The Angular Router instance. Use this to navigate programmatically within the shell.
config	ConfigService from @yuuvis/client-core	The shell’s configuration service. Use config.get(key) to read a top-level key from the shell’s runtime configuration JSON. The available keys depend on your deployment’s configuration file.

Examples

Opening an External URL

This example adds a help button that opens a support link defined in the shell’s runtime configuration:

src/app/app.config.ts

import { provideShellActionButtons, ShellActionButtonConfigAPI } from '@yuuvis/client-shell';

provideShellActionButtons([
  {
    iconName: 'help',
    tooltip: 'my.app.action-button.help.tooltip',
    onClick: (api: ShellActionButtonConfigAPI) => {
      const supportLink = api.config.get('support')?.link;
      if (supportLink) {
        window.open(supportLink, '_blank');
      }
    }
  }
])

The tooltip value is an i18n key — register it in your app’s translation files. api.config.get('support') reads the support object from the shell’s runtime configuration; the link is only opened when the value is present.

Navigating Within the Shell

Use api.router to navigate to a shell route programmatically:

provideShellActionButtons([
  {
    iconName: 'settings',
    tooltip: 'my.app.action-button.settings.tooltip',
    onClick: (api: ShellActionButtonConfigAPI) => {
      api.router.navigate(['/settings']);
    }
  }
])

Multiple Buttons

Pass multiple button definitions in the array. Buttons appear top-to-bottom in the sidebar in the order they are declared:

provideShellActionButtons([
  {
    iconName: 'help',
    tooltip: 'my.app.action-button.help.tooltip',
    onClick: (api) => { /* ... */ }
  },
  {
    iconName: 'feedback',
    tooltip: 'my.app.action-button.feedback.tooltip',
    onClick: (api) => { /* ... */ }
  }
])

Delegating to a Service

For actions beyond simple navigation or config reads, delegate to an Angular service. Use Angular’s inject() function inside the callback to access any service registered in the application’s injector:

src/app/app.config.ts

import { inject } from '@angular/core';
import { provideShellActionButtons } from '@yuuvis/client-shell';
import { HelpService } from './help.service';

provideShellActionButtons([
  {
    iconName: 'help',
    tooltip: 'my.app.action-button.help.tooltip',
    onClick: () => {
      inject(HelpService).openHelpPanel();
    }
  }
])

Best Practices

Best Practices

• Always guard against missing config values. api.config.get() returns undefined when a key is not present. Check for the value before using it — runtime configuration is deployment-specific and may differ between environments.
• Use i18n keys for tooltips, not literal strings. The tooltip is passed through the Angular translate pipe. A plain string will be displayed as-is rather than translated.
• Keep onClick handlers to a single, well-defined action — navigate to a route, open a URL, or call a service method. Avoid embedding multi-step logic or conditional branching directly in the callback.
• Prefer api.router and api.config for common needs. For services beyond Router and ConfigService, use Angular’s inject() inside the callback or delegate to a dedicated service.