feat(NgxSvgSprite): add a directive for rendering symbols of svg sprites

[RobbyRabbitman]

A directive for rendering symbols of svg sprites. It is done with the use element.

Import

import { NgxSvgSpriteFragment } from 'ngxtension/svg-sprite';

Usage

In this example the symbol github of the fontawesome svg sprite fa-brands is rendered. A symbol is identified by a fragment. Learn more about URLs.

<svg fragment="github" sprite="fa-brands"></svg>

Without NgxSvgSpriteFragment:

<svg viewBox="0 0 496 512">
	<use href="assets/fontawesome/sprites/brands.svg#github"></use>
</svg>

With Directive Composition Api

In your project you can utilize the Directive Composition Api to create specific svg sprites.

In this example a fontawesome brands svg sprite is created.

<svg faBrand="github"></svg>

@Directive({
	selector: 'svg[faBrand]',
	standalone: true,
	hostDirectives: [
		{ directive: NgxSvgSpriteFragment, inputs: ['fragment:faBrand'] },
	],
})
export class FaBrandSvg {
	constructor() {
		inject(NgxSvgSpriteFragment).sprite = 'fa-brands';
	}
}

Configuration

In order to render a symbol, sprites have to be provided.

provideSvgSprites(
	createSvgSprite({
		name: 'fa-brands',
		baseUrl: 'assets/fontawesome/sprites/brands.svg',
	}),
);

The name property can reference any arbitrary value, but should be unique, since you can register multiple different svg sprites.

The sprite input of the NgxSvgSpriteFragment should reference the name property of a provided sprite.

Auto View Box

When a symbol of an svg sprite is rendered the viewBox attribute or height and width should be set. The svg element does not copy/use the viewBox attribute of the symbol in the svg sprite, therefore the svg will have default dimensions of 300x150 px, which is probably not preferred.

Per default when an svg sprite is registered, the svg sprite is fetched with js in addition. NgxSvgSpriteFragment will copy the viewBox attribute of the symbol to its host.

This behavior can be disabled.

Disable via DI

Auto View Box is disabled for the svg sprite.

provideSvgSprites(
	createSvgSprite({
		name: 'fa-brands',
		baseUrl: 'assets/fontawesome/sprites/brands.svg',
		autoViewBox: false,
	}),
);

Disable via autoViewBoxDisabled Input

Auto View Box is disabled for a svg element, when the autoViewBoxDisabled input is set to false.

<svg fragment="github" sprite="fa-brands" autoViewBoxDisabled></svg>

Disable via viewBox Attribute

Auto View Box is disabled for a svg element, when the viewBox attribute already is defined.

<svg fragment="github" sprite="fa-brands" viewBox="0 0 32 32"></svg>

Classes

When the classes function is set, a list of classes will be added by the NgxSvgSpriteFragment to its host.

provideSvgSprites(
	createSvgSprite({
		name: 'my-sprite',
		baseUrl: 'path/to/my/sprite.svg',
		classes: (fragment) => ['some-class', `some-other-class-${fragment}`],
	}),
);

Url

Per default when using the createSvgSprite function, the url will return '${baseUrl}#${fragment}'. This can be overwritten:

provideSvgSprites(
	createSvgSprite({
		name: 'my-sprite',
		baseUrl: 'path/to/my/sprite.svg',
		url: (baseUrl, fragment) => `${baseUrl}#some-prefix-${fragment}`,
	}),
);

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit d97625f. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

⌛ The following targets are in progress

• nx affected --target=build --parallel=3 --exclude=docs
• nx affected --target=test --parallel=3 --ci --code-coverage

✅ Successfully ran 1 target

• nx affected --target=lint --parallel=3

---

Sent with 💌 from NxCloud.

[RobbyRabbitman]

@nartc Hello again, could you please review this feature and share your thoughts on the API 😄

[ajitzero]

@RobbyRabbitman A general question: This doesn't need to be specific to fonticons/fontAwesome. Do you think we can make this configurable to accept any SVG file? We could also refactor to load the SVG file lazily on first use.

Thoughts?

[RobbyRabbitman]

@ajitzero The configuration accepts any url. That means any svg can be used. The example shows fontawesome. I think the js fetch is already lazy, I should add test to verify that. The directive adds an use element, I don't know if the use element has a lazy loading feature like the img element. I will research that.

[nartc]

Thank you for the contributions. Couple of nits and suggestions.

[RobbyRabbitman]

Thank you for the review and your suggestions, I will refactor the code 😄

[RobbyRabbitman]

@ajitzero I think possible solutions for lazy loading are Intersection Observers: You can even use Angulars new deferrable views to skip setting up the observers by yourself. Maybe like so:

@defer (on viewport) {
    <svg faBrand="github"></svg>
} @placeholder {
    <span>Some skeletton</span>
}