@grandgular/link

Angular service for managing HTML <link> 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 <link> 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

npm install @grandgular/link

Usage

Basic Setup

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

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

Add a canonical link

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

Add multiple links

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

Update existing link

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

Get link element

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

Remove link

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

Advanced Usage

Custom attributes

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

Force creation (duplicate links)

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

Custom selector for updates

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

API Reference

LinkDefinition

Type representing all possible attributes including:

• Standard attributes: rel, href, crossorigin, type, etc.
• Custom attributes via index signature
• Modern attributes: fetchpriority, imagesrcset, referrerpolicy

Methods

| 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