npm package: @rchernando/solar-icons
Description: Tree-shakable Solar Icons for Angular. 1200+ icons, 6 styles, fully typed.
Author: rchernando
Latest version: 4.0.2

# @rchernando/solar-icons

**Tree-shakable Solar Icons for Angular** — 1200+ icons, 6 style variants, 7400+ icon definitions, fully typed.

Based on the [Solar Icons Set](https://www.figma.com/design/puR3qYt8bIoTxf7IzW9b17/Solar-Icons-Set-(Community)) from Figma Community.

---

## Features

- **Tree-shakable** — Only the icons you import end up in your bundle
- **Typed** — Full TypeScript types for icon names (`IconSet`) and styles (`StyleSet`)
- **6 style variants** — `bold`, `bold-duotone`, `broken`, `line-duotone`, `linear`, `outline`
- **37 categories** — From arrows to weather
- **Standalone & NgModule** — Works with both patterns
- **Angular 15+** — Compatible with Angular 15, 16, 17, 18, 19 and future versions
- **OnPush friendly** — Uses `ChangeDetectionStrategy.OnPush`
- **CSS color** — Icons inherit `currentColor`, style with CSS

---

## Angular compatibility

| Angular version | Library version |
|-----------------|-----------------|
| 15, 16, 17, 18, 19+ | 3.x |
| 19 | 2.x |
| 18 | 1.x |

---

## Installation

```bash
npm install @rchernando/solar-icons
```

---

## Setup

### Standalone applications (recommended)

Register only the icons you need using `provideSolarIcons()`:

```typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideSolarIcons } from '@rchernando/solar-icons';
import {
  AltArrowDownBold,
  AltArrowDownOutline,
  AltArrowUpBold
} from '@rchernando/solar-icons';

export const appConfig: ApplicationConfig = {
  providers: [
    provideSolarIcons(
      AltArrowDownBold,
      AltArrowDownOutline,
      AltArrowUpBold
    )
  ]
};
```

Import `SolarIconsComponent` in the components where you use it:

```typescript
import { Component } from '@angular/core';
import { SolarIconsComponent } from '@rchernando/solar-icons';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [SolarIconsComponent],
  template: `<solar-icon name="alt-arrow-down" iconStyle="bold"></solar-icon>`
})
export class ExampleComponent {}
```

### NgModule applications

Use `SolarIconsModule.withIcons()` in your module:

```typescript
import { NgModule } from '@angular/core';
import { SolarIconsModule } from '@rchernando/solar-icons';
import {
  AltArrowDownBold,
  AltArrowDownOutline
} from '@rchernando/solar-icons';

@NgModule({
  imports: [
    SolarIconsModule.withIcons(
      AltArrowDownBold,
      AltArrowDownOutline
    )
  ]
})
export class AppModule {}
```

### Lazy-loaded modules

You can register additional icons in lazy-loaded routes or modules. They are added to the same global registry:

```typescript
// feature.routes.ts
import { Routes } from '@angular/router';
import { provideSolarIcons } from '@rchernando/solar-icons';
import { HeartBold, StarBold } from '@rchernando/solar-icons';

export const featureRoutes: Routes = [
  {
    path: '',
    providers: [provideSolarIcons(HeartBold, StarBold)],
    component: FeatureComponent
  }
];
```

### Manual registration

You can also register icons imperatively via the service:

```typescript
import { Component } from '@angular/core';
import { SolarIconsService, SolarIconsComponent } from '@rchernando/solar-icons';
import { HeartBold, HeartOutline } from '@rchernando/solar-icons';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [SolarIconsComponent],
  template: `<solar-icon name="heart" iconStyle="bold"></solar-icon>`
})
export class ExampleComponent {
  constructor(iconService: SolarIconsService) {
    iconService.addIcons(HeartBold, HeartOutline);
  }
}
```

---

## Usage

### Basic

```html
<solar-icon name="heart" iconStyle="bold"></solar-icon>
```

### Size

Default size is `24px × 24px`. Use `size` as shorthand, or `width`/`height` individually:

```html
<!-- Shorthand: sets both width and height -->
<solar-icon name="heart" iconStyle="bold" size="48px"></solar-icon>

<!-- Individual control -->
<solar-icon name="heart" iconStyle="bold" width="48px" height="32px"></solar-icon>
```

### Color

Icons use `currentColor`, so they inherit the text color of their parent:

```html
<!-- Inherits parent color -->
<div style="color: red;">
  <solar-icon name="heart" iconStyle="bold"></solar-icon>
</div>

<!-- With CSS class -->
<solar-icon name="heart" iconStyle="bold" class="text-blue-500"></solar-icon>
```

### Dynamic icons

All inputs are reactive. Changing them updates the icon:

```typescript
@Component({
  template: `
    <solar-icon [name]="iconName" [iconStyle]="style"></solar-icon>
    <button (click)="toggle()">Toggle</button>
  `
})
export class DynamicExample {
  iconName: IconSet = 'heart';
  style: StyleSet = 'bold';

  toggle() {
    this.iconName = this.iconName === 'heart' ? 'star' : 'heart';
  }
}
```

### Accessibility

Icons are decorative by default. For accessible icons, add `aria-label`:

```html
<!-- Decorative icon (no screen reader announcement) -->
<button>
  <solar-icon name="heart" iconStyle="bold" aria-hidden="true"></solar-icon>
  Like
</button>

<!-- Standalone meaningful icon -->
<solar-icon name="heart" iconStyle="bold" role="img" aria-label="Favorite"></solar-icon>
```

---

## API Reference

### `<solar-icon>` Component

| Input       | Type       | Default    | Description                          |
|-------------|------------|------------|--------------------------------------|
| `name`      | `IconSet`  | —          | Icon name (required)                 |
| `iconStyle` | `StyleSet` | `'outline'`| Style variant                        |
| `size`      | `string`   | —          | Shorthand for width and height       |
| `width`     | `string`   | `'24px'`   | Width (any CSS unit)                 |
| `height`    | `string`   | `'24px'`   | Height (any CSS unit)                |

### `SolarIconsService`

| Method | Signature | Description |
|--------|-----------|-------------|
| `addIcons` | `(...icons: IconDefinition[]) => void` | Register icons in the global registry |
| `getIcon` | `(name: string, style: string) => string \| undefined` | Retrieve SVG data for an icon |
| `hasIcon` | `(name: string, style?: string) => boolean` | Check if an icon is registered |

### `provideSolarIcons(...icons)`

Provider function for standalone applications. Returns `Provider[]` for use in `ApplicationConfig.providers` or route `providers`.

### `SolarIconsModule`

NgModule that exports `SolarIconsComponent`.

| Method | Signature | Description |
|--------|-----------|-------------|
| `withIcons` | `(...icons: IconDefinition[]) => ModuleWithProviders<SolarIconsModule>` | Register icons via module import |

### Types

```typescript
// Shape of each icon definition
interface IconDefinition {
  name: string;
  data: string;   // Raw SVG markup
  style: string;
}

// Union type of all available icon names
type IconSet = 'alt-arrow-down' | 'alt-arrow-left' | ... ;

// Available style variants
type StyleSet = 'bold' | 'bold-duotone' | 'linear' | 'outline' | 'broken' | 'line-duotone';
```

---

## Style variants

Each icon is available in 6 styles:

| Style | Constant suffix | Description |
|-------|----------------|-------------|
| `bold` | `Bold` | Solid filled |
| `bold-duotone` | `BoldDuotone` | Filled with two-tone effect |
| `broken` | `Broken` | Broken/dashed strokes |
| `line-duotone` | `LineDuotone` | Line with two-tone effect |
| `linear` | `Linear` | Clean single-weight lines |
| `outline` | `Outline` | Outlined strokes |

**Naming convention for imports:**

The export name is `PascalCase(iconName) + PascalCase(style)`.

| Icon name | Style | Import name |
|-----------|-------|-------------|
| `alt-arrow-down` | `bold` | `AltArrowDownBold` |
| `heart` | `outline` | `HeartOutline` |
| `4k` | `bold-duotone` | `KBoldDuotone` |
| `bicycling` | `linear` | `BicyclingLinear` |

---

## Icon categories

| Category | Import path (from index) | Examples |
|----------|-------------------------|----------|
| arrow | Arrow directions | `alt-arrow-down`, `arrow-left`, `double-alt-arrow-up` |
| arrow-actions | Download, upload, navigation actions | `download`, `upload`, `login`, `logout`, `export` |
| astronomy | Space and celestial objects | `earth`, `rocket`, `planet`, `star-fall`, `ufo` |
| bulding-infrastructure | Buildings and structures | `buildings`, `city`, `home`, `hospital`, `garage` |
| business-statistic | Charts and analytics | `chart`, `graph-up`, `pie-chart`, `diagram-up` |
| call | Phone and calling | `phone`, `incoming-call`, `end-call`, `call-chat` |
| design-tools | Design and editing tools | `crop`, `palette`, `pipette`, `ruler`, `layers` |
| electronic-devices | Hardware and electronics | `laptop`, `smartphone`, `keyboard`, `monitor`, `tv` |
| essentional-ui | Core UI elements | `add-circle`, `check-circle`, `close-circle`, `home`, `filter` |
| face-emotions-stickers | Emojis and expressions | `smile-circle`, `sad-circle`, `emoji-funny-circle` |
| files | File types and actions | `file`, `file-text`, `code-file`, `zipfile` |
| folders | Folder operations | `folder`, `add-folder`, `folder-open`, `move-to-folder` |
| food-kitchen | Food and cooking | `chef-hat`, `cup-hot`, `donut`, `wineglass` |
| hands | Hand gestures | `hand-heart`, `hand-shake`, `hand-stars` |
| home-furniture | Furniture and home items | `bed`, `sofa`, `lamp`, `fridge`, `armchair` |
| like | Hearts, stars, medals | `heart`, `star`, `like`, `dislike`, `medal-star` |
| list | Lists and sorting | `list`, `checklist`, `sort-by-alphabet`, `playlist` |
| map-location | Maps and navigation | `map`, `compass`, `gps`, `route`, `global` |
| medicine | Medical and health | `pill`, `stethoscope`, `heart-pulse`, `syringe`, `dna` |
| message-conversation | Messaging and mail | `chat-dots`, `letter`, `inbox`, `pen`, `plain` |
| money | Finance and payments | `card`, `wallet`, `dollar`, `banknote`, `tag-price` |
| nature-travel | Nature and travel | `leaf`, `fire`, `suitcase`, `bonfire`, `flame` |
| networking-it-programming | Code and networking | `code`, `bug`, `hashtag`, `programming`, `wi-fi-router` |
| notes-documents | Documents and archives | `document`, `clipboard`, `notebook`, `archive` |
| notifications | Alerts and notifications | `bell`, `notification-unread`, `bell-off` |
| school | Education | `book`, `bookmark`, `calculator`, `diploma`, `backpack` |
| search | Search magnifiers | `magnifer`, `magnifer-zoom-in`, `magnifer-zoom-out` |
| security | Security and privacy | `lock`, `shield`, `key`, `eye`, `incognito`, `qrcode` |
| settings-fine-tuning | Settings and controls | `settings`, `tuning`, `widget` |
| shopping-ecommerce | Shopping and e-commerce | `bag`, `cart`, `shop` |
| sports | Sports and fitness | `basketball`, `football`, `running`, `swimming`, `dumbbell` |
| text-formatting | Text editing | `text-bold`, `text-italic`, `text-underline`, `link` |
| time | Time and calendar | `clock-circle`, `calendar`, `alarm`, `hourglass`, `stopwatch` |
| transport-parts-service | Transport and vehicles | `bus`, `gas-station`, `wheel`, `tram`, `scooter` |
| users | User profiles | `user`, `user-plus`, `user-check`, `users-group-rounded` |
| video-audio-sound | Media playback | `play`, `pause`, `camera`, `microphone`, `volume-loud` |
| weather | Weather conditions | `sun`, `cloud`, `moon`, `snowflake`, `temperature` |

---

## Tree-shaking

In v3.x, icons are **not auto-registered**. Only the icons you explicitly import and register are included in your bundle. This can reduce bundle size dramatically compared to v2.x.

```typescript
// Only these 2 icons end up in your bundle:
import { HeartBold, HeartOutline } from '@rchernando/solar-icons';
```

---

## Migration from v2.x

v3.x is a breaking change. Icons are no longer auto-registered.

### Before (v2.x)

```typescript
// All 7400+ icons were bundled automatically
import { SolarIconsComponent } from '@rchernando/solar-icons';

@Component({
  imports: [SolarIconsComponent],
  template: `<solar-icon name="heart" iconStyle="bold"></solar-icon>`
})
export class MyComponent {}
```

### After (v3.x)

```typescript
// Only import what you need
import { SolarIconsComponent, SolarIconsService } from '@rchernando/solar-icons';
import { HeartBold } from '@rchernando/solar-icons';

@Component({
  imports: [SolarIconsComponent],
  template: `<solar-icon name="heart" iconStyle="bold"></solar-icon>`
})
export class MyComponent {
  constructor(iconService: SolarIconsService) {
    iconService.addIcons(HeartBold);
  }
}
```

Or register globally via providers:

```typescript
// app.config.ts
import { provideSolarIcons } from '@rchernando/solar-icons';
import { HeartBold, HeartOutline, StarBold } from '@rchernando/solar-icons';

export const appConfig: ApplicationConfig = {
  providers: [
    provideSolarIcons(HeartBold, HeartOutline, StarBold)
  ]
};
```

---

## License

MIT