diff --git a/.all-contributorsrc b/.all-contributorsrc
index e50fd6bc..9e1be152 100644
--- a/.all-contributorsrc
+++ b/.all-contributorsrc
@@ -23,7 +23,7 @@
},
{
"login": "the-ult",
- "name": "Arjen Althoff",
+ "name": "The Ult",
"avatar_url": "https://avatars.githubusercontent.com/u/4863062?v=4",
"profile": "https://github.com/the-ult",
"contributions": [
diff --git a/README.md b/README.md
index 2ae85ef4..0c373985 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,73 @@
-# angular-tabler-icons
+# angular-tabler-icons
[](https://tabler.io/icons)
[]()
[]()
+
[](#contributors-)
-
-## Description
+
This package allows you to use the [Tabler Icons](https://tabler.io/icons) in your angular applications. Tabler Icons is a set of free MIT-licensed high-quality SVG icons for you to use in your web projects. Each icon is designed on a 24x24 grid and a 2px stroke.
-## Install
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+ - [Available icons](#available-icons)
+ - [Standalone (Recommended)](#standalone-recommended)
+ - [Component](#component)
+ - [HTML](#html)
+ - [Styling icons](#styling-icons)
+ - [Options](#options)
+ - [Pick all icons](#pick-all-icons)
+ - [NgModule (Legacy)](#ngmodule-legacy)
+ - [Generate a module to host the icons you'll import\_](#generate-a-module-to-host-the-icons-youll-import_)
+ - [Import assets](#import-assets)
+ - [Import IconsModule](#import-iconsmodule)
+ - [Use it in template\_](#use-it-in-template_)
+- [Bundle Size Considerations](#bundle-size-considerations)
+- [Angular compatibility](#angular-compatibility)
+ - [Angular 19 | \>= v3.22](#angular-19---v322)
+ - [Breaking Changes](#breaking-changes)
+ - [Migration Guide](#migration-guide)
+ - [Angular 18 | \<= v3.10.0](#angular-18---v3100)
+- [Contributing](#contributing)
+ - [How to rebuild for newer tabler icons version](#how-to-rebuild-for-newer-tabler-icons-version)
+- [Contributors ✨](#contributors-)
+
+## Quick Start
+
+For a minimal setup, install the package, import the icons you need, and start using them in your templates:
-_1. Install the package_
-
-```sh
+```bash
npm install angular-tabler-icons
-# or
-yarn add angular-tabler-icons
+```
+
+```ts
+import { Component } from "@angular/core";
+import { TablerIconComponent, provideTablerIcons } from "angular-tabler-icons";
+import { IconNumber123 } from "angular-tabler-icons/icons";
+
+@Component({
+ selector: "app-demo",
+ standalone: true,
+ imports: [TablerIconComponent],
+ providers: [provideTablerIcons({ IconNumber123 })],
+ template: '',
+})
+export class DemoComponent {}
```
## Usage
-### Standalone
+### Available icons
+
+List of available icons:
+
+This version includes **Tabler Icons v3.26.0**, see [changelog](https://tabler.io/icons/changelog) to know which icons are available.
+
+### Standalone (Recommended)
If you are using Standalone Components, use the `provideTablerIcons()`
@@ -63,37 +106,31 @@ export class StandaloneComponent {}
```html
```
-## Available icons
-
-List of available icons:
-
-This version includes **Tabler Icons v3.26.0**, see [changelog](https://tabler.io/icons/changelog) to know which icons are available.
-
-## Styling icons
+### Styling icons
Each icon can be styled separately with CSS:
```html
-
+
```
```css
@@ -115,7 +152,7 @@ Each icon can be styled separately with CSS:
}
```
-## Options
+### Options
Some options are available to configure the module:
@@ -137,7 +174,7 @@ import * as TablerIcons from "angular-tabler-icons/icons";
export class IconsModule {}
```
-## Pick all icons
+### Pick all icons
You can import all icons at once by doing the following. However, keep in mind that by doing this, all icons will end up in your application bundle. While this may not be much of an issue for prototyping, **it is not recommended for any application that you plan to release**.
@@ -154,17 +191,17 @@ export class IconsModule {}
### NgModule (Legacy)
-_1. Generate a module to host the icons you'll import_
+#### Generate a module to host the icons you'll import\_
```sh
ng generate module icons
```
-_2. Import assets_
+#### Import assets
You need to import:
-- TablerIconsModule, as it contains the `` component
+- TablerIconsModule, as it contains the `<>` component
- The icons that you need
We put this in IconsModule for modularity. See example below:
@@ -191,11 +228,11 @@ const icons = {
export class IconsModule {}
// NOTES:
-// 1. We add TablerIconsModule to the 'exports', since the component will be used in templates of parent module
+// 1. We add TablerIconsModule to the 'exports', since the <> component will be used in templates of parent module
// 2. Don't forget to pick some icons using TablerIconsModule.pick({ ... })
```
-_3. Import IconsModule_
+#### Import IconsModule
If you are using NgModules, import it this way:
@@ -213,29 +250,130 @@ import { IconsModule } from "./icons.module";
export class MyModule {}
```
-_4. Use it in template_
+#### Use it in template\_
After importing the _IconsModule_ in your feature or shared module, use the icons as follows:
```html
-
-
-
-
+
+
+
+
```
-## Angular version compatibility
+## Bundle Size Considerations
+
+⚠️ **Important**: Importing all icons will increase your bundle size. For production:
+
+✅ **Recommended**:
+
+- Import only the icons you need
+- Use tree-shakable standalone providers
+- Consider lazy loading icon modules
+
+❌ **Not recommended**:
+
+- Importing all icons at once
+- Using `TablerIcons.*` import syntax
+
+## Angular compatibility
+
+| Angular | angular-tabler-icons |
+| ------- | ------------------------------------------------------------------ |
+| 19 | 3.22.0+ [see "Angular 19" section](#angular-19---v322) |
+| 18 | 2.40.1 - 3.1.0 [see "Angular 18" section](<(#angular-18---v3100)>) |
+| 17 | 2.40.1+ |
+| 16 | 2.21.1+ |
+| 15 | 1.117.1+ |
+| 14 | 1.72.1+ |
+| 13 | 1.53.1+ |
+| 12 | 1.41.3+ |
+| 11 | 1.41.0+ |
+
+**N.B.**
+
+_Versions are aligned with the [tabler iconst](https://github.com/tabler/tabler-icons/releases) versions._
+
+_Therefore angular-tabler-icons is not following the official SemVer._
+
+### Angular 19 | >= v3.22
+
+This version uses Angular's Signals API and standalone components by default.
+
+#### Breaking Changes
-| Angular | angular-tabler-icons |
-| ------- | -------------------- |
-| 18 & 19 | 3.22.0+ |
-| 17 | 2.40.1+ |
-| 16 | 2.21.1+ |
-| 15 | 1.117.1+ |
-| 14 | 1.72.1+ |
-| 13 | 1.53.1+ |
-| 12 | 1.41.3+ |
-| 11 | 1.41.0+ |
+- Deprecated `TablerIconsModule.pick()` in favor of `provideTablerIcons()`
+- Icons now use standalone components
+- Requires Angular 19.0.0 or higher
+- Updated to ES2022 module format
+
+#### Migration Guide
+
+From NgModule syntax:
+
+```typescript
+@NgModule({
+ imports: [TablerIconsModule.pick(icons)]
+})
+```
+
+To standalone syntax:
+
+```typescript
+import { provideTablerIcons } from "angular-tabler-icons";
+
+export const appConfig: ApplicationConfig = {
+ providers: [provideTablerIcons({ icons })],
+};
+```
+
+or
+
+```typescript
+@Component({
+ selector: 'my-standalone-component',
+ imports: [TablerIconComponent],
+ /**
+ * Provide the icons which you want to use in this component.
+ */
+ providers: [
+ provideTablerIcons({
+ IconNumber123,
+ IconHeartFilled,
+ }),
+ ],
+,
+})
+export class StandaloneComponent {}
+```
+
+### Angular 18 | <= v3.10.0
+
+Angular 18 is _not officially supported_, however with `3.1.x` you can use the [overrides](https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#overrides) in your package.json when using `npm`
+
+```json
+"overrides": {
+ "angular-tabler-icons": {
+ "peerDependencies": {
+ "@angular/common": "18.x",
+ "@angular/core": "18.x"
+ }
+ }
+}
+```
+
+With `pnpm` you can use the [peerDependencyRules.allowVersions](https://pnpm.io/package_json#pnpmpeerdependencyrulesallowedversions) in your package.json
+
+```json
+"pnpm": {
+ "peerDependencyRules": {
+ "allowedVersions": {
+ "angular-tabler-icons>@angular/common": "18",
+ "angular-tabler-icons>@angular/core": "18"
+ }
+ }
+ },
+```
## Contributing
@@ -247,7 +385,7 @@ yarn lib:generate # generate components from Tabler Icons
yarn lib:build # build angular library
```
-## How to rebuild for newer tabler icons version
+### How to rebuild for newer tabler icons version
1. Run GitHub actions workflow `Automatic PR on Tabler Icons Release`, with new Tabler Icons version (e.g. `2.40.0`). This workflow will create automatically a new Pull Request.
2. Approve and Merge the generated Pull Request.
@@ -265,8 +403,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
