GoGrab Space Icons Guide

This guide explains which icon systems we use across the platform and how to use them correctly.

Quick Reference

1. Material Icons (Classic)

Font: Google Material Icons (ligature-based)

Loading: Must be added to the app's index.html:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" />

Some apps load multiple variants:

<link href="https://fonts.googleapis.com/icon?family=Material+Icons|Material+Icons+Outlined|Material+Icons+Round" rel="stylesheet" />

Usage:

<span class="material-icons">add</span>
<span class="material-icons spin">sync</span>
<span class="material-icons" [class]="statusClass">check_circle</span>

Where it's loaded: gograb-ai, gograb-admin, gograb-dev, space-admin

Common in: Vitto Hub (channel manager, webhooks, memory, cost dashboard, observatory), AI panel tabs, ux-tabs

Ligature names (use text content, not a class): add, arrow_back, check, check_circle, close, delete, error, forum, info, security, sync, verified_user, etc.

2. Material Symbols (Modern Variants)

Font: Google Material Symbols — rounded, outlined, or sharp variants with variable font support.

Loading: Via styles.scss (e.g. in gograb-space):

@import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200');
@import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,[email protected],100..700,0..1,-50..200');

Usage:

<span class="material-symbols-rounded">palette</span>
<span class="material-symbols-outlined">arrow_back</span>
<span class="material-symbols-sharp">close</span>

<!-- Filled variant (font variation) -->
<span class="material-symbols-rounded" style="font-variation-settings: 'FILL' 1;">star</span>

Where it's used: Widget builder, widget showcase, variant creator, UX Icons gallery

Sizing: Use utility classes or inline styles:

.material-symbols-rounded { font-size: 1.25rem; }
.icon-small { font-size: 16px; }
.icon-medium { font-size: 24px; }
.icon-large { font-size: 32px; }

3. Font Awesome

Source: CDN or @fortawesome/fontawesome-free package

Loading (gograb-space index.html):

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css"
      integrity="sha512-DTOQO9RWCH3ppGqcWaEA1BIZOC6xxalwEsw9c2QQeAIftl+Vegovlnee1c9QX4TctnWMn13TZye+giMm8e2LwA=="
      crossorigin="anonymous" referrerpolicy="no-referrer" />

Usage:

<i class="fa fa-star"></i>
<i class="fas fa-check"></i>
<i class="far fa-heart"></i>
<i class="fab fa-github"></i>

Primary use: The Icon widget in the page builder (IconWidget in @libs-widgets/widgets). Users pick icons via class strings like fa fa-star, fas fa-check.

Styles: fas (solid), far (regular), fab (brands)

4. ux-icon (Remote SVG Icons)

Library: @libs-ux/ux-icons

Source: Remote server at https://gograb.io/media/icons/ (structure: svg/static, svg/outline, badges, etc.)

Setup: Initialize IconService in app config:

import { IconService } from '@libs-ux/ux-icons';

{
  provide: APP_INITIALIZER,
  useFactory: (iconService: IconService) => () => {
    iconService.initialize('https://gograb.io/media/icons', {
      enableCache: true,
      defaultSize: '24px',
      defaultColor: 'currentColor'
    });
  },
  deps: [IconService],
  multi: true
}

Usage:

<ux-icon icon="svg/home" size="24px" />
<ux-icon icon="svg/static/close" size="32px" color="#3b82f6" title="Close" />
<ux-icon icon="badges/star" className="ux-icon--lg" />

Features: Lazy loading, caching, multi-color SVG support, accessibility.

5. local-icon (Local SVG Assets)

Component: LocalIconComponent (gograb-space app)

Usage: For SVGs stored in the app's assets or similar local paths.

<local-icon icon="/assets/icons/my-icon.svg" size="24px" />
<local-icon icon="/assets/icons/custom.svg" color="#6366f1" title="Custom icon" />

6. UxIconComponent (Editor UI)

Library: @editor-ui / @libs-ui/editor-ui

Multi-source support: Material, Font Awesome, SVG, URL, custom.

Usage:

<lib-ux-icon name="home"></lib-ux-icon>
<lib-ux-icon name="settings" size="lg" [clickable]="true" (iconClick)="onClick($event)"></lib-ux-icon>
<lib-ux-icon [config]="iconConfig"></lib-ux-icon>

Config example:

iconConfig: UxIconConfig = {
  name: 'star',
  sourceType: 'material',  // 'material' | 'fontawesome' | 'svg' | 'url' | 'custom'
  size: 'xl',
  color: '#ffc107',
  spin: true,
  ariaLabel: 'Star icon'
};

App-by-App Icon Loading

Important: If you add icons to a template and they render as text (e.g. "chat" instead of an icon), the font is not loaded in that app. Add the appropriate <link> to that app's index.html or styles.scss.

Best Practices

1. Be consistent within a feature: Vitto Hub uses material-icons; widget builder uses material-symbols-rounded. Don't mix unless necessary.

2. Accessibility: Add aria-label or title for decorative icons that convey meaning:

   <span class="material-icons" aria-label="Close dialog">close</span>
   

3. Loading states: Use the spin class for loading indicators:

   <span class="material-icons spin">sync</span>
   

4. Icon widget: Use Font Awesome classes (fa fa-*) when configuring the Icon widget—that's what the widget expects.

5. New features: Prefer Material Symbols (rounded/outlined) for new UI—they're more modern and support variable fonts. Use Material Icons (classic) when matching existing Vitto Hub or AI panel patterns.

Troubleshooting

Icons show as plain text

Cause: Font not loaded in the app.

Fix: Add the appropriate stylesheet to the app's index.html or styles.scss (see loading sections above).

Material Symbols not rendering

Cause: Material Symbols use a different font URL than Material Icons. They require the css2 API:

@import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,[email protected],100..700,0..1,-50..200');

ux-icon not loading

Cause: IconService not initialized, or icon path doesn't exist on the server.

Fix: Ensure IconService.initialize() runs in an APP_INITIALIZER. Check https://gograb.io/media/icons/ structure and images.txt files.