import { KbqIconModule } from '@koobiq/components/icon';

KbqIcon

componentCopy link to KbqIcon

Renders an icon on the element it is applied to: a @koobiq/icons font glyph by default, or an inline <svg> when the name resolves through a configured KbqIconRegistry. A name that does not resolve falls back to the font class, and every later name is resolved again.

The host is aria-hidden by default: an icon carries no text of its own, and in nearly every place the library and its consumers use one it repeats a label that is already there. A meaningful icon opts out with aria-hidden="false", and then has to supply its own role="img" and aria-label.

@Component({ selector: '[kbq-icon]' })
class KbqIcon extends KbqColorDirective {
    readonly ariaHidden = input<boolean | undefined>(undefined, {
        alias: 'aria-hidden'
    });
    readonly iconSize = input<number | undefined>();
    autoColor = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasError: boolean;
    iconName: string | undefined;
    get colorClassName(): string;
    getHostElement(): HTMLElement;
    setDefaultColor(color: T): void;
}
aria-hiddeninputCopy link to aria-hiddenboolean | undefined

Whether the icon is hidden from assistive technology. Left unbound, it falls back to defaultAriaHidden, which is true for a decorative icon and false for an interactive one.

iconSizeinputCopy link to iconSizenumber | undefined

Rendered size of the icon in pixels. Left unset, the size is read from the _<px> suffix of the icon name (kbq-plus_16 → 16), which is the @koobiq/icons convention; a name without one is rendered at whatever size the surrounding styles give it.

autoColorinputCopy link to autoColorboolean | undefined

Whether the icon follows the error state of the host it sits in (a form field, for one), painting itself red while that host reports an error.

colorinputCopy link to colorT | null | undefined

Color of the component. A value set in code holds until the input changes, and the default color is used while both are unset or falsy.

hasErrorCopy link to hasErrorboolean

Whether the icon takes the error color whatever its color is. Set by a host that tints the icons it holds, such as KbqEmptyState.

iconNameCopy link to iconNamestring | undefined

Name of an icon within a @koobiq/icons. Accepts "namespace:name" syntax.

colorClassNameCopy link to colorClassNamestring

current class name of color

setDefaultColor()Copy link to setDefaultColor()void

this color will be used as a default value. For example [color]="'' | false | undefined | null".

KbqIconButton

componentCopy link to KbqIconButton

An icon that acts as a button. Applied to a native <button> it only adds the styling; applied to any other element — <i> is what the library itself mostly uses — it also supplies the semantics the element does not have: role="button" and aria-disabled. It does not synthesize Enter/Space activation itself — attach a (keydown.enter)/(keydown.space) listener where it is used.

It has no text of its own, so give it an aria-label (or an aria-labelledby); in dev mode it warns when it has neither.

It extends KbqIcon for the rendering, but deliberately does not register under that DI token: a contentChild(KbqIcon) is looking for a decorative icon to position or tint, and an interactive control is not one. See the note on KbqIconItem.

@Component({ selector: '[kbq-icon-button]' })
class KbqIconButton extends KbqIcon {
    readonly size = input<KbqIconButtonSize>('normal');
    tabindex = input<number | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly ariaHidden = input<boolean | undefined>(undefined, {
        alias: 'aria-hidden'
    });
    readonly iconSize = input<number | undefined>();
    autoColor = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasError: boolean;
    iconName: string | undefined;
    get colorClassName(): string;
    getHostElement(): HTMLElement;
    setDefaultColor(color: T): void;
}
sizeinputCopy link to sizeKbqIconButtonSize

Size of the icon button.

tabindexinputCopy link to tabindexnumber | null | undefined

Position of the button in the tab order. A disabled button is taken out of it entirely.

disabledinputCopy link to disabledboolean | undefined

Whether the button is disabled.

aria-hiddeninputCopy link to aria-hiddenboolean | undefined

Whether the icon is hidden from assistive technology. Left unbound, it falls back to defaultAriaHidden, which is true for a decorative icon and false for an interactive one.

iconSizeinputCopy link to iconSizenumber | undefined

Rendered size of the icon in pixels. Left unset, the size is read from the _<px> suffix of the icon name (kbq-plus_16 → 16), which is the @koobiq/icons convention; a name without one is rendered at whatever size the surrounding styles give it.

autoColorinputCopy link to autoColorboolean | undefined

Whether the icon follows the error state of the host it sits in (a form field, for one), painting itself red while that host reports an error.

colorinputCopy link to colorT | null | undefined

Color of the component. A value set in code holds until the input changes, and the default color is used while both are unset or falsy.

hasErrorCopy link to hasErrorboolean

Whether the icon takes the error color whatever its color is. Set by a host that tints the icons it holds, such as KbqEmptyState.

iconNameCopy link to iconNamestring | undefined

Name of an icon within a @koobiq/icons. Accepts "namespace:name" syntax.

colorClassNameCopy link to colorClassNamestring

current class name of color

setDefaultColor()Copy link to setDefaultColor()void

this color will be used as a default value. For example [color]="'' | false | undefined | null".

KbqIconItem

componentCopy link to KbqIconItem

An icon on a filled round background — the status badge of an alert or an empty state. Decorative like KbqIcon, and hidden from assistive technology by the same default.

Host metadata is inherited from KbqIcon through ɵɵInheritDefinitionFeature; DI tokens are not, so a contentChild(KbqIcon) does not match an icon item. That is deliberate — a host that wants both asks for both, the way KbqAlert does, and telling them apart is what lets it report two projected icons.

@Component({ selector: '[kbq-icon-item]' })
class KbqIconItem extends KbqIcon {
    readonly fade = input<boolean>(false);
    readonly big = input<boolean>(false);
    readonly ariaHidden = input<boolean | undefined>(undefined, {
        alias: 'aria-hidden'
    });
    readonly iconSize = input<number | undefined>();
    autoColor = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasError: boolean;
    iconName: string | undefined;
    get colorClassName(): string;
    getHostElement(): HTMLElement;
    setDefaultColor(color: T): void;
}
fadeinputCopy link to fadeboolean

Whether the background is the translucent "fade" variant of the color rather than the solid one.

biginputCopy link to bigboolean

Whether the item is rendered at the larger of its two sizes.

aria-hiddeninputCopy link to aria-hiddenboolean | undefined

Whether the icon is hidden from assistive technology. Left unbound, it falls back to defaultAriaHidden, which is true for a decorative icon and false for an interactive one.

iconSizeinputCopy link to iconSizenumber | undefined

Rendered size of the icon in pixels. Left unset, the size is read from the _<px> suffix of the icon name (kbq-plus_16 → 16), which is the @koobiq/icons convention; a name without one is rendered at whatever size the surrounding styles give it.

autoColorinputCopy link to autoColorboolean | undefined

Whether the icon follows the error state of the host it sits in (a form field, for one), painting itself red while that host reports an error.

colorinputCopy link to colorT | null | undefined

Color of the component. A value set in code holds until the input changes, and the default color is used while both are unset or falsy.

hasErrorCopy link to hasErrorboolean

Whether the icon takes the error color whatever its color is. Set by a host that tints the icons it holds, such as KbqEmptyState.

iconNameCopy link to iconNamestring | undefined

Name of an icon within a @koobiq/icons. Accepts "namespace:name" syntax.

colorClassNameCopy link to colorClassNamestring

current class name of color

setDefaultColor()Copy link to setDefaultColor()void

this color will be used as a default value. For example [color]="'' | false | undefined | null".

KbqIconRegistry

serviceCopy link to KbqIconRegistry
@Injectable({ providedIn: 'root' })
class KbqIconRegistry {
    addSvgIcon(
        name: string,
        url: SafeResourceUrl,
        options?: KbqIconOptions
    ): void;
    addSvgIconLiteral(
        name: string,
        literal: SafeHtml,
        options?: KbqIconOptions
    ): void;
    addSvgIconInNamespace(
        namespace: string,
        name: string,
        url: SafeResourceUrl,
        options?: KbqIconOptions
    ): void;
    addSvgIconLiteralInNamespace(
        namespace: string,
        name: string,
        literal: SafeHtml,
        options?: KbqIconOptions
    ): void;
    addSvgIconSet(url: SafeResourceUrl, options?: KbqIconOptions): void;
    addSvgIconSetInNamespace(
        namespace: string,
        url: SafeResourceUrl,
        options?: KbqIconOptions
    ): void;
    getNamedSvgIcon(
        name: string,
        namespace?: string
    ): Observable<SVGElement>;
}
addSvgIcon()Copy link to addSvgIcon()void

Registers an SVG icon by URL in the default namespace.

addSvgIconLiteral()Copy link to addSvgIconLiteral()void

Registers an SVG icon from an inline HTML string in the default namespace.

addSvgIconInNamespace()Copy link to addSvgIconInNamespace()void

Registers an SVG icon by URL under the given namespace.

addSvgIconLiteralInNamespace()Copy link to addSvgIconLiteralInNamespace()void

Registers an SVG icon from an inline HTML string under the given namespace.

addSvgIconSet()Copy link to addSvgIconSet()void

Registers an SVG sprite file in the default namespace. Icons are looked up by their symbol id.

addSvgIconSetInNamespace()Copy link to addSvgIconSetInNamespace()void

Registers an SVG sprite file under the given namespace. Duplicate URLs are silently ignored.

getNamedSvgIcon()Copy link to getNamedSvgIcon()Observable<SVGElement>

Emits a cloned SVGElement for the given name. Accepts "namespace:name" syntax.

kbqIconsDictProvider

functionCopy link to kbqIconsDictProvider

Registers a name→URL dictionary as an icon resolver. Values are fetched at runtime through HttpClient.

A value starting with < is taken as inline markup and passed through Angular's HTML sanitizer, which drops <svg> wholesale — register inline icons with KbqIconRegistry.addSvgIconLiteral(name, sanitizer.bypassSecurityTrustHtml(svg)) instead, where the markup is a SafeHtml the application has explicitly vouched for.

Example
kbqIconsDictProvider({ 'chevron-down-s_16': '/assets/icons/chevron-down-s_16.svg' })
function kbqIconsDictProvider(dict: Record<string, string>): Provider;

kbqIconsProvider

functionCopy link to kbqIconsProvider

Configures the icon registry to load icons from one or more SVG sprite assets.

function kbqIconsProvider(...sprites: KbqIconsConfig[]): Provider;

kbqIconsResolverProvider

functionCopy link to kbqIconsResolverProvider

Registers a resolver function that maps icon names to SVG strings or URLs. Multiple resolvers can be registered; they are tried in registration order.

function kbqIconsResolverProvider(resolver: KbqIconResolver): Provider;

KbqIconButtonSize

typeCopy link to KbqIconButtonSize

Size options for KbqIconButton.

  • compact: 16px icon with padding, 24×24px container.
  • normal: 24px icon, no padding.
type KbqIconButtonSize = 'compact' | 'normal';

KbqIconOptions

interfaceCopy link to KbqIconOptions
interface KbqIconOptions {
    viewBox?: string;
    withCredentials?: boolean;
}

KbqIconResolver

typeCopy link to KbqIconResolver

A function that resolves an icon name to either an inline SVG string or a URL string. Return null to indicate this resolver does not handle the given name.

type KbqIconResolver = (name: string) => string | null;

KbqIconsConfig

interfaceCopy link to KbqIconsConfig
interface KbqIconsConfig {
    spriteUrl: string;
    namespace?: string;
}
spriteUrlCopy link to spriteUrlstring

URL to the SVG sprite file. Must be served as a static asset.

namespaceoptionalCopy link to namespacestring

Optional namespace to register the sprite under.

KBQ_ICON_RESOLVER

constCopy link to KBQ_ICON_RESOLVER

Multi-valued injection token for icon resolver functions. Resolvers are tried in registration order; the first non-null result wins.

const KBQ_ICON_RESOLVER: InjectionToken<KbqIconResolver[]>;

KBQ_ICONS_CONFIG

constCopy link to KBQ_ICONS_CONFIG
const KBQ_ICONS_CONFIG: InjectionToken<KbqIconsConfig[]>;
Suggestions for improvement
If you found a mistake or want to improve the article, create an issue on GitHub.