@grandgular/link

[//]: # ([](https://www.npmjs.com/package/@grandgular/link))

Angular service for managing HTML elements in the document head. Provides a type-safe API to dynamically add, update, query, and remove link elements.

v1.0.0 - Stable Release

✅ Production Ready - The library has been battle-tested during the beta period and is now stable for production use.

Features

- 🛠️ Full control over elements
- 🧩 Supports all standard and custom link attributes
- 🔍 Query existing links with CSS selectors
- ♻️ Smart update system (finds and updates existing links)
- 🏷️ Type-safe API with LinkDefinition interface
- ⚡ Lightweight (~2KB gzipped)
- 🅰️ Angular 16+ compatible

Installation

``bash
npm install @grandgular/link
`

Usage

$3

Import and inject the Link service in your component or service:

`typescript
import { Component, inject } from '@angular/core';
import { Link } from '@grandgular/link';

@Component({
selector: 'app-root',
template: ...
})
export class AppComponent {
link = inject(Link);
// or
// constructor(private link: Link) {}
}
`

API Examples

$3

`typescript
this.link.addTag({
rel: 'canonical',
href: 'https://example.com/page'
});
`

$3

`typescript
this.link.addTags([
{ rel: 'preconnect', href: 'https://api.example.com' },
{ rel: 'stylesheet', href: '/styles.css' }
]);
`

$3

`typescript
this.link.updateTag({
rel: 'canonical',
href: 'https://example.com/new-url'
});
`

$3

`typescript
const canonical = this.link.getTag('rel="canonical"');
`

$3

`typescript
this.link.removeTag('rel="canonical"');
`

Advanced Usage

$3

`typescript
this.link.addTag({
rel: 'preload',
href: '/font.woff2',
as: 'font',
type: 'font/woff2',
crossorigin: 'anonymous'
});
`

$3

`typescript
this.link.addTag(
{ rel: 'stylesheet', href: '/theme.css' },
true // force creation even if exists
);
`

$3

`typescript
this.link.updateTag(
{ href: 'https://new-cdn.com/style.css' },
'href="https://old-cdn.com/style.css"'
);
`

API Reference

$3

Type representing all possible attributes including:
- Standard attributes: rel, href, crossorigin, type, etc.
- Custom attributes via index signature
- Modern attributes: fetchpriority, imagesrcset, referrerpolicy

$3

| Method | Description |
|--------|-------------|
| addTag(tag: LinkDefinition, forceCreation?: boolean) | Adds a new link element or returns existing one if found. When forceCreation is true, always creates new element. |
| addTags(tags: LinkDefinition[], forceCreation?: boolean) | Adds multiple link elements. Returns array of created/existing elements. |
| getTag(attrSelector: string) | Returns first link element matching the attribute selector (e.g. 'rel="canonical"') or null if not found. |
| getTags(attrSelector: string) | Returns all link elements matching the attribute selector as an array (empty array if none found). |
| updateTag(tag: LinkDefinition, selector?: string) | Updates existing link (found by selector or auto-detected from tag) or creates new one if not found. |
| removeTag(attrSelector: string) | Removes link element matching the attribute selector. |
| removeTagElement(link: HTMLLinkElement)` | Removes specific link element from DOM. |

License

MIT © Grandgular