Apollo Icons

Apollo's Icon package with full TypeScript support.

Installation

npm install @xplortech/apollo-icons@latest

Usage

Basic Usage

import octicons from '@xplortech/apollo-icons';

// Access an icon by name
const icon = octicons['calendar-refresh'];

// Generate SVG string
const svg = icon.toSVG();
// => '<svg version="1.1" width="16" height="16" viewBox="0 0 16 16" ...>...</svg>'

TypeScript Support

The package includes full TypeScript definitions with autocomplete for all icon names:

import octicons, { Icon, IconName, SVGOptions } from '@xplortech/apollo-icons';

// Icon names are typed - you get autocomplete!
const icon = octicons['calendar-refresh']; // ✓ Type-safe

// TypeScript will catch typos
const invalid = octicons['calender-refresh']; // ✗ Error: not a valid IconName

SVG Options

Customize the SVG output with options:

// Specify width (height scales proportionally)
icon.toSVG({ width: 24 });

// Specify height (width scales proportionally)
icon.toSVG({ height: 32 });

// Add custom CSS classes
icon.toSVG({ class: 'my-icon text-primary' });

// Add aria-label for accessibility (removes aria-hidden)
icon.toSVG({ 'aria-label': 'Refresh calendar' });

Getting Icons by Name

Use getIcon() to safely retrieve an icon by name:

import octicons from '@xplortech/apollo-icons';

// Get an icon by name (returns Icon or undefined)
const icon = octicons.getIcon('calendar-refresh');
if (icon) {
  console.log(icon.toSVG());
}

// Works with both direct access and getIcon()
const directIcon = octicons['calendar-refresh'];
const helperIcon = octicons.getIcon('calendar-refresh');
// Both return the same icon object

Finding Icons by Tag

Use getIconsByTag() to find all icons that match a specific keyword/tag:

import octicons from '@xplortech/apollo-icons';

// Find all icons tagged with 'audio'
const audioIcons = octicons.getIconsByTag('audio');
// => [volume, headphones-4, microphone-3, ...]

// Iterate over matching icons
audioIcons.forEach(icon => {
  console.log(icon.symbol); // Icon name
  console.log(icon.toSVG({ width: 24 })); // SVG output
});

// Find icons for calendars
const calendarIcons = octicons.getIconsByTag('calendar');

// Find icons for navigation
const navIcons = octicons.getIconsByTag('arrow');

Icon Properties

Each icon object has the following properties:

const icon = octicons['calendar-refresh'];

icon.symbol;    // 'calendar-refresh' - the icon name
icon.keywords;  // ['calendar-refresh', 'reload', 'sync', ...] - searchable tags
icon.heights;   // { '16': {...}, '24': {...}, ... } - available sizes
icon.toSVG();   // Function to generate SVG string

Available Heights

Icons are available in multiple sizes. The toSVG() method automatically selects the best size based on the requested dimensions:

// Request height 16 - uses 16px variant
icon.toSVG({ height: 16 });

// Request height 24 - uses 24px variant
icon.toSVG({ height: 24 });

// Request height 20 - uses closest available (16px scaled up)
icon.toSVG({ height: 20 });

Icon Name Aliasing (Deprecation Notice)

Apollo Icons supports legacy icon names (called "apollo names") alongside the current naming convention (called "nucleo names"). Apollo names are deprecated and will be removed in the next major release.

Deprecation Warnings

When you access an icon using a deprecated apollo name, you'll see a console warning:

// Using a deprecated apollo name
const icon = octicons['ai'];
// Console warning: [octicons] Deprecation warning: Icon name "ai" is deprecated
// and will be removed in the next major release. Please use "add-magic" instead.

// Using the recommended nucleo name (no warning)
const icon = octicons['add-magic'];

Note: Each deprecated name only warns once per session to avoid console spam.

Migrating from Apollo Names

If you're using deprecated apollo names, update them to nucleo names:

// ❌ Deprecated (apollo names)
octicons['ai'];
octicons['search'];
octicons['home'];
octicons['mail'];
octicons['edit'];

// ✅ Recommended (nucleo names)
octicons['add-magic'];
octicons['magnifier'];
octicons['house-4'];
octicons['envelope'];
octicons['compose-2'];

Checking Icon Availability

Both naming conventions work with the in operator:

'ai' in octicons; // true (but deprecated)
'add-magic' in octicons; // true (recommended)

Using getIcon() During Migration

The getIcon() helper supports both naming conventions and provides a safe way to check icon availability:

// Works with both naming conventions
const icon1 = octicons.getIcon('ai'); // Warns about deprecation
const icon2 = octicons.getIcon('add-magic'); // No warning

// Returns undefined for non-existent icons
const icon3 = octicons.getIcon('non-existent'); // undefined

API Reference

octicons[iconName]

Access an icon by its name. Returns an Icon object.

const icon = octicons['calendar-refresh'];

Note: Supports both nucleo names (recommended) and apollo names (deprecated with warnings).

octicons.getIcon(name: string): Icon | undefined

Get an icon by name with safe undefined handling. Returns the Icon object if found, or undefined if not found.

const icon = octicons.getIcon('calendar-refresh');
if (icon) {
  console.log(icon.toSVG());
}

Note: Supports both nucleo names (recommended) and apollo names (deprecated with warnings).

octicons.getIconsByTag(tag: string): Icon[]

Returns an array of all icons that include the specified tag in their keywords.

const audioIcons = octicons.getIconsByTag('audio');

Icon.toSVG(options?: SVGOptions): string

Generates an SVG string for the icon.

Options:

| Option | Type | Description | | ------------ | -------- | ---------------------------------------- | | width | number | Width of the SVG in pixels | | height | number | Height of the SVG in pixels | | class | string | Additional CSS classes to add | | aria-label | string | Accessible label (removes aria-hidden) |