# @odx/icons

A lightweight library for displaying icons as custom elements. This package provides flexible imports, allowing you to include only what you need to optimize your project.

## Installation (npm)

Install the library via npm:

```bash
npm i @odx/icons
```

## Usage

The library provides a custom element `<odx-icon>` to display icons. You can choose between different icon sets (core, safety, ...) or import individual icons to reduce your bundle size.

> **We rely on the esm module behavior in order to keep a global state.** If you load an asset from a CDN ensure that the same module of **@odx/assets-utils** is used throughout your application. One common technique is the usage of an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) (`<script type="importmap">`).

### Import custom element:

```js
import '@odx/icons';
```

### Import specific icon sets

To optimize your bundle, you can import only the specific icon set you need:

```js
// Core icons (default set)
import '@odx/icons/core';

// Medical icons 
import '@odx/icons/medical';

// Safety icons 
import '@odx/icons/safety';
```

### Import individual icons

To optimize your bundle, you can import only the specific icons you need:

```js
import '@odx/icons/core/user';
```

## Element API

### Properties

- **name**: string - `<set-name>::<name>` or `<name>` with default set (core)
- **size**: string - one of `xs` | `sm` | `md` | `lg` | `xl` | `xxl`
  
#### Deprecated
- **set**: string - `<set-name>` - Use name property with format `<set>::<name>` instead

### Size Attribute

The size attribute provides predefined size options for the icon. These options correspond to CSS variables that can be customized globally in your project. The available values are:

- `xs`: `--odx-size-100` - fallback: `16px`
- `sm`: `--odx-size-125` - fallback: `20px`
- `md`: `--odx-size-150` - fallback: `24px`
- `lg`: `--odx-size-200` - fallback: `32px`
- `xl`: `--odx-size-225` - fallback: `36px`
- `xxl`: `--odx-size-300` - fallback: `48px`

> The size tokens (`--odx-size-*`) are provided by the **@odx/design-tokens** package.

Set the CSS `font-size` property on the element to define a custom size.

## Example Usage

### HTML Example

```html
<script type="module">
  import '@odx/icons';
  import '@odx/icons/core';
</script>

<odx-icon name="user"></odx-icon>
<odx-icon name="core::user"></odx-icon>

<odx-icon name="safety::alarm"></odx-icon>
<odx-icon name="alarm" set="safety"></odx-icon>
```

#### CDN

```html
<script src="https://esm.sh/@odx/icons" type="module"></script>
<script src="https://esm.sh/@odx/icons/<set-name>" type="module"></script>
```

### JavaScript Example

```js
// import the custom element
import '@odx/icons';

// import the core icon set
import '@odx/icons/core';

// Create an icon dynamically
const icon = document.createElement('odx-icon');
icon.name='core::user'

document.body.appendChild(icon);
```

### Import specific icon sets
To optimize your bundle, you can import only the specific icon set you need:

```js
// All icon sets
import '@odx/icons/all';

// Core icons (default set)
import '@odx/icons/core';
```

### SCSS Example

```scss
@use "@odx/icons/scss" as odxIcons;

.my-icon-user {
  @include odxIcons.icon("core::user");
}

.my-icon-alarm {
  @include odxIcons.icon("safety::alarm");
}
```

> We use the `::after` pseudo element to apply our svg image mask, ensure you don't override those styles.

#### Migration from Version < 4.x.x

In order to migrate from versions prior to 4.x.x, you need to update your imports and usage as follows:

- Remove icon font imports, as they are no longer supported.
- Update your icon imports to use the new module structure.

If you are using the CSS variant of the icons

```HTML
<i class="odx-icon" data-icon-name="user": data-icon-set="core"></i>
```

you will need to switch to the new custom element or import our compatibility script

```js
 // use this instead of '@odx/icons'
import '@odx/icons/compat';
```

### Browser Support

This library leverages modern web technologies such as Shadow DOM for encapsulation and CSSStyleSheet.replaceSync() for efficient stylesheet updates. It targets the ES2022 specification, taking advantage of the latest JavaScript features. These technologies are widely supported in most modern browsers.

#### Supported Browsers:

- Chrome **97+**
- Edge **97+**
- Firefox **104+**
- Safari **14+**
- Opera **83+**

## Live demo ⭐

For a overview of all available assets please refer to our [**Asset Viewer**](https://assets.draeger.com/icons).