DEV Community: Duncan Faulkner

Scanning public Angular apps with axe, and naming the component behind each finding

Duncan Faulkner — Tue, 06 Oct 2026 21:38:04 +0000

The plan was to offer people a free accessibility scan of their Angular app. Most real Angular apps sit behind a login, though, and the public ones are often brochure sites with little to test. So I scanned Angular apps that are public and widely used instead, to see what the ecosystem looks like.

Two things came out of it. The raw scanner reported on the wrong page three times. And when it was right, it told me where a problem was in the DOM but not which component to fix.

Raw scanner output needs checking

I ran axe-core over interactive pages. Three times it returned a list of violations for a page that wasn't the app:

What I scanned	What axe saw
`/login` on the RealWorld reference app	The app is hosted as a single-page app with no server fallback, so the deep link served GitHub Pages' "File not found" page. Eight of the contrast failures I nearly wrote up were GitHub's 404 styling.
Deep links into ngx-admin's dashboard	They redirect to a theme-picker splash screen. My first pass returned 484 violations, all from that splash screen. I only reached the dashboard after clicking a theme card.
RealWorld's live demo (`angular.realworld.io`)	Three issues. The home feed said "Loading articles… No articles are here… yet." The demo's backend has no data, so I had scanned an empty shell.

In each case the number looked believable and meant nothing. I caught it by reading the flagged HTML by hand: <strong>File not found</strong> gives it away.

Two smaller things came up too. Two axe builds disagreed about whether one ngx-admin button failed button-name; a stricter manual check said it did. And I discarded a "serious" aria-hidden-focus finding on cdk-focus-trap-anchor, which appears on every Angular app that uses the CDK focus trap. It's a framework pattern rather than an app bug.

A scanner tells you where to look. You still have to check what it found.

A selector doesn't say which component to fix

When axe is right, it gives you a CSS selector such as .start-search or a[href$="johndoe"] > img. That locates a node in the DOM. In an Angular app the fix lives in a component, often one reused across many pages, and the selector doesn't name it.

Angular already has that information. In a development build it exposes a debug API on window.ng that maps a DOM node to the component whose template rendered it. Pass axe's findings through that and each violation comes with a component name.

So I added a headless report mode to our open-source @ngbracket/a11y-devtools. It drives a running dev build in a real browser, runs the same axe rules, and attributes each violation to the app component that rendered it. The report is grouped by component, and a --fail-on switch makes it usable in CI. The app under test doesn't change; report mode reads Angular's debug API from outside.

It needs a dev build, because production builds don't include window.ng. That's why I could only do this for open-source apps I could run myself, and not for other people's deployed apps. The three scans above were raw axe against production. The two apps below were scanned with report mode against a dev build. The survey after them is raw axe again.

ngx-admin

ngx-admin is a widely forked Angular admin template. Against its dashboard, report mode found 83 violation instances across 9 distinct rules, each attributed to a component.

The header search button has no accessible name, so a screen reader announces it only as "button". Raw axe identifies it as .start-search. Report mode attributes it to HeaderComponent, and shows the chain of Nebular components between the button and the header:

NbButtonComponent › NbSearchComponent › NbActionComponent › NbActionsComponent › HeaderComponent

It walks past the third-party UI components to the app component you would open to fix it. The rest of the run was sorted the same way:

Finding	Component	What it is
Unlabelled `sidebar-toggle` link	`HeaderComponent`	A template bug
Unlabelled social links	`FooterComponent`	Demo content you wouldn't ship
25 "content outside a landmark" warnings	`OneColumnLayoutComponent`, via Nebular's menu	A gap in the app's layout shell

The search button comes from Nebular

The component chain also showed that the search button comes from Nebular's nb-search component, which ngx-admin uses. In Nebular's source, nb-search renders its open and close buttons as icon-only <button> elements with no accessible name. Every ngx-admin fork inherits that.

A look through Nebular's component templates found two aria-label attributes in the whole library, and icon-only controls without names in nb-window, the calendar's month arrows, the flip and reveal cards, and nb-chat. Attribution showed which layer the bug belongs to as well as which component, so I reported it to Nebular.

RealWorld

RealWorld is the reference app many developers copy when they learn Angular. Its live demo showed three shell-level issues because the feed was empty. Running the source in dev with real content gave a fuller picture.

image-alt and link-name both trace to ArticleMetaComponent, the author byline on each article card:

ArticleMetaComponent › ArticlePreviewComponent › ArticleListComponent › HomeComponent

It's rendered in every preview on the page. The author's avatar has no alt and the author link has no text. axe reports eight instances: four images without alt text and four empty links. That's one component with one mistake, rendered on every card, and one fix covers all eight.

A quick survey of other apps

For breadth, I ran raw axe over a few more public apps. These are production builds, so there's no attribution, and the same caution about raw numbers applies.

OpenProject is an actively maintained product. On its public work-package table, the coloured work-package type labels fail contrast. The "Task" label is #08a5df text on white, a ratio of 2.82:1 against the 4.5:1 minimum in WCAG 1.4.3. A sortable column header also has no text.

On Angular's own sites, a raw scan flagged colour contrast on angular.dev and a group of aria-allowed-role instances on the Angular Material docs. I'd verify those before filing anything.

On counting: report the number of distinct rules as well as node instances. Most of ngx-admin's 83 instances are one landmark rule firing many times. The instance count shows how noisy a page is; the distinct-rule count is closer to how many fixes it needs. Our report shows both.

What kept coming up

Across OpenProject, RealWorld and ngx-admin, the same kinds of problem recurred:

Landmark structure: no <main>, and content outside any landmark.
Accessible names: icon-only buttons and links with no name.
Basics: lang on <html>, empty table headers, colour contrast.

Few of these are unusual widget problems. Most come from how components are put together into pages, or from one shared component that every page reuses. A page scan reports these as selectors. Knowing the owning component means you fix it once instead of on every page.

Where NgBracket fits

NgBracket's component packs are built for this kind of gap. A pack ships an assembled piece of UI, such as a data table, a login flow or a dashboard shell, with the landmarks, accessible names, keyboard support and focus management already in place. They're built to support WCAG 2.2 AA. Every change is checked in CI with axe and accessibility-tree snapshots, and the interactive components also have automated NVDA checks.

@ngbracket/a11y-devtools is the tool I used here. It's free, open source and runs only in development. Add the provider for a live overlay while you work, or run report mode over your dev build in CI, and each finding names its owning component.

Notes

Automated tools like axe cover roughly a third of WCAG. Keyboard and screen-reader behaviour still need testing by a person.

Every finding here is from September 2026, on the pages and builds I tested. I sent fixes where I could: pull requests to RealWorld (#363) and ngx-admin (#6073), and an issue about the missing names in Nebular (#3318). OpenProject tracks issues on its own instance rather than GitHub.

If you'd like a scan like this of your Angular app, get in touch, or start with the free packs. No card is needed.

A WCAG AA checklist for Angular components

Duncan Faulkner — Sun, 12 Jul 2026 08:00:00 +0000

This is the checklist I run before an Angular component ships. It covers WCAG Level AA, groups the items by area, and includes Angular code for the common fixes.

I've written Angular for ten years, and for most of them accessibility was something I'd do after the feature worked. It usually didn't get done. A written checklist made it part of finishing a component.

Automated tools such as axe and Lighthouse check roughly a third of WCAG. They find missing alt text, low text contrast and duplicate ids. They can't tell whether the tab order makes sense, where focus goes after a dialog closes, or whether a live region is announced. Each item below ends with one of these labels:

Automated: axe or a similar tool checks it.
Partly automated: a tool catches some cases, and you check the rest.
Manual: you have to test it yourself.

1. Keyboard and focus

Everything interactive works with the keyboard alone. Put the mouse away and use the component with Tab, Enter, Space and the arrow keys. Manual.
Native elements are used where possible. A <button> is focusable, works with the keyboard and is announced as a button. A <div (click)> is none of those. If you're adding role="button" and a keydown handler to a div, use a button instead. Partly automated.
Focus is always visible. Don't set outline: none without a replacement. Use :focus-visible so keyboard users see a ring and mouse users don't. The ring needs 3:1 contrast against the background. Manual.

  :focus-visible {
    outline: 2px solid #1a56db; /* your focus colour, at least 3:1 against the background */
    outline-offset: 2px;
  }

Tab order follows reading order. Don't use a positive tabindex. If the visual order and the DOM order differ, change the DOM. Partly automated.
Modal dialogs trap focus and return it to the trigger when they close. The CDK Dialog service does both. If you build your own dialog, cdkTrapFocus handles the trap, and you have to return focus to the trigger yourself. Manual.

  <div cdkTrapFocus cdkTrapFocusAutoCapture role="dialog" aria-modal="true" aria-labelledby="title">
    <h2 id="title">Confirm deletion</h2>
    …
  </div>

Nothing else traps the keyboard. You can always Tab out of a component. An open modal is the only exception. Manual.

2. Focus after something changes

Tools can't check most of this section.

Route changes move focus. After navigation in a single-page app, focus stays on an element that no longer exists. Move it to the new page's heading. Manual.

  this.router.events.pipe(filter(e => e instanceof NavigationEnd))
    .subscribe(() => {
      const h1 = this.doc.querySelector('main h1') as HTMLElement | null;
      h1?.focus(); // h1 needs tabindex="-1"
    });

Opening a menu, drawer or dialog moves focus into it, and closing it returns focus to the trigger. Manual.
Deleting an item moves focus to a sensible place, such as the next row or the list heading. Focus shouldn't fall back to <body>. Manual.
A skip link lets keyboard users jump past the navigation to <main>. Partly automated.

3. Semantics and ARIA

Use a native element when one exists. Add ARIA only when it doesn't.

The page has landmarks: one <main>, plus <nav>, <header> and <footer> where they apply. Partly automated.
Each page has one <h1>, and heading levels don't skip. Screen-reader users move around a page by its headings. Partly automated.
Custom widgets have the right role and state. Set them in the host object rather than with @HostBinding:

  @Component({
    selector: 'ngbr-switch',
    host: {
      'role': 'switch',
      '[attr.aria-checked]': 'checked()',
      '[attr.aria-disabled]': 'disabled() || null',
      'tabindex': '0',
      '(keydown.enter)': 'toggle()',
      '(keydown.space)': 'toggle(); $event.preventDefault()',
    },
  })
  export class NgbrSwitch { /* checked = signal(false) … */ }

Partly automated: axe checks that the role and attributes are valid, but not that the state changes when it should.

Icon-only buttons have an accessible name, such as aria-label="Close". An icon font or SVG on its own has no name. Automated.
aria-describedby and aria-labelledby point at ids that exist. A missing id means nothing is announced. Partly automated: axe reports a missing id as needing review, so a CI check that fails only on violations won't catch it.
Native elements don't repeat their own role. <button role="button"> and <nav role="navigation"> add nothing. Manual.

4. Forms and errors

Every input has a <label> with a matching for and id. A placeholder isn't a label. Partly automated: axe flags inputs with no name at all, but accepts a placeholder as a name.
Required fields are marked in code with required or aria-required="true", as well as visually. Manual.
Errors are linked to their field and announced. Connect the message with aria-describedby, set aria-invalid, and give the message role="alert" so it's read when it appears. Manual.

  <label for="email">Email</label>
  <input id="email" type="email"
         [attr.aria-invalid]="showError()"
         [attr.aria-describedby]="showError() ? 'email-error' : null">
  @if (showError()) {
    <p id="email-error" role="alert">Enter a valid email address.</p>
  }

On submit, focus moves to the first error or to an error summary, so keyboard users don't have to search for it. Manual.
Errors are shown with text or an icon as well as colour (see section 5). Manual.

5. Colour, contrast and motion

Text meets AA contrast: 4.5:1 for body text and 3:1 for large text. Partly automated: axe can't work out contrast over translucent layers, gradients or images.
Control borders, icons and focus indicators meet 3:1 against what's behind them (WCAG 1.4.11). axe doesn't check this. Manual.
Colour isn't the only way information is shown (WCAG 1.4.1). A red border needs an icon or text too. Charts and status indicators are where this fails most often. Manual.
The UI works at 200% zoom, and reflows at 400% without horizontal scrolling or clipped content. Manual.
Animation respects prefers-reduced-motion. Motion can trigger vestibular disorders. Manual.

  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
      animation-duration: 0.01ms !important;
      transition-duration: 0.01ms !important;
    }
  }

Contrast holds in light and dark themes. Take colours from theme tokens rather than hard-coding them, and run the contrast check in both themes. Partly automated.

6. Dynamic content

Updates that happen without a page load are announced: "Showing 12 results", "Saved", "Loading". Use the CDK's LiveAnnouncer rather than writing your own live region. Manual.

  private announcer = inject(LiveAnnouncer);
  // after a filter runs:
  this.announcer.announce(`${count} results`, 'polite');

Loading and busy states are exposed, for example with aria-busy="true" on the region that is updating. Manual.
Images have useful alt text, and decorative images have alt="". Automated for missing alt, manual for whether the text is useful.
Charts have a text version. An SVG chart gives a screen reader nothing to read, so render the same data as a visually hidden <table>. No tool flags a chart without one. Manual.

How to run it

Automated pass. Add @axe-core/playwright or jest-axe to CI so the automated items can't regress.
Keyboard pass. Put the mouse away and Tab through the whole flow. Most manual items show up within a minute.
Screen-reader pass. Use VoiceOver (Cmd+F5 on macOS) or NVDA (free on Windows). Listen for whether what you hear matches what's on screen.

Most components fail on the same dozen items, which is why a written checklist helps.

NgBracket is a set of Angular component packs built to support WCAG 2.2 AA, with keyboard support, focus management, ARIA and chart data tables built in. The conformance report lists how each criterion is tested and the known limitations. You can start with the free packs without a card.

Managing focus in Angular: dialogs, drawers, route changes and deleted rows

Duncan Faulkner — Fri, 10 Jul 2026 19:33:30 +0000

Accessibility checklists list focus management as one item. In practice it covers many separate decisions, and it's often what separates an app that passes an automated audit from one a keyboard user can get through.

The model that helped me is this: focus is a cursor, and there is only one. For someone using a keyboard or a screen reader, focus is where they are in your app. Mouse users don't think about it, because their eyes and pointer move independently. Everyone else has one position, and every time your UI changes what's on screen, you need to answer one question:

Where does focus go now?

If the answer is wrong, the user ends up somewhere useless. Usually that's the top of the page or <body>, and they have to Tab through all of your navigation to get back. Automated tools won't tell you, because where focus went after a state change isn't in a DOM snapshot. Below are four places where Angular apps commonly get it wrong.

1. Route changes

This is the most common focus bug in Angular apps, and the hardest to notice. When you navigate a server-rendered site, the browser loads a new document and focus starts at the top. In a single-page app, the router swaps part of the DOM and focus stays on whatever you clicked, which is usually a link that no longer exists. Screen-reader users get no sign that the page changed.

The fix is to move focus to the new page's heading after each navigation:

@Component({ /* … */ })
export class App {
  private readonly router = inject(Router);
  private readonly doc = inject(DOCUMENT);

  constructor() {
    this.router.events
      .pipe(
        filter((e) => e instanceof NavigationEnd),
        takeUntilDestroyed(),
      )
      .subscribe(() => {
        const heading = this.doc.querySelector('main h1') as HTMLElement | null;
        heading?.focus();
      });
  }
}

Two more things are needed. The <h1> needs tabindex="-1" so it can take focus from script without joining the tab order. And you want a skip link as the first focusable element, so people can jump past the navigation to <main>:

<a class="skip-link" href="#main-content">Skip to main content</a>

With one subscription, every route change now moves focus to the new page and a screen reader reads its heading.

2. Dialogs: trap focus, then return it

A modal has two focus jobs, and many hand-written dialogs only do one of them.

While the dialog is open, focus must stay inside it. Tab shouldn't reach the page behind. The CDK handles this correctly, including wrapping from the last element to the first:

<div cdkTrapFocus cdkTrapFocusAutoCapture role="dialog" aria-modal="true" aria-labelledby="title">
  <h2 id="title">Delete this project?</h2>
  <!-- … -->
</div>

When the dialog closes, focus must go back to the element that opened it. Otherwise it falls to <body> and the user starts again from the top of the page. This is the part people forget:

private returnFocusTo: HTMLElement | null = null;

open() {
  this.returnFocusTo = this.doc.activeElement as HTMLElement;
  this.isOpen.set(true);
}

close() {
  this.isOpen.set(false);
  this.returnFocusTo?.focus();
}

If you're opening real modals, the Dialog service in @angular/cdk/dialog does both jobs for you. restoreFocus is on by default.

3. Drawers, menus and disclosures

A cart drawer, a navigation flyout and a filter panel follow the same rule as a modal: move focus in when it opens, and return it to the trigger when it closes. If a drawer opens but focus stays behind the overlay, the user tabs through content they can't see.

For menus with arrow-key navigation, ListKeyManager and FocusKeyManager from @angular/cdk/a11y give you roving focus. Arrow keys move between items and Tab leaves the widget, without you writing the keydown handling yourself.

4. Deleting the focused item

If you delete the row that has focus and do nothing else, focus falls to <body>. Send it somewhere sensible instead: the next row, or the list heading if you deleted the last row. In Angular the difficulty is timing. You have to wait for the signal update to reach the DOM before the new target exists. Use afterNextRender:

private readonly host = inject(ElementRef<HTMLElement>);
private readonly injector = inject(Injector);

removeAt(index: number) {
  this.items.update((list) => list.filter((_, i) => i !== index));

  afterNextRender(
    () => {
      const rows = this.host.nativeElement.querySelectorAll<HTMLElement>('[data-row]');
      const next = rows[Math.min(index, rows.length - 1)];
      (next ?? this.host.nativeElement.querySelector<HTMLElement>('h2'))?.focus();
    },
    { injector: this.injector },
  );
}

The same pattern works when adding an item (focus the new input), loading more results (focus the first new one) and a failed submit (focus the first error).

Don't move focus when nobody asked

Managing focus doesn't mean moving it all the time. Avoid these two patterns:

autofocus on page load. Moving focus into a search box on every load gets in the way of people who navigate by heading or landmark. Only autofocus inside a modal or on a page with a single purpose.
Moving focus on scroll or hover. Focus should follow something the user did on purpose, such as a click, a key press or an explicit action.

Keep the focus indicator visible. :focus-visible shows it to keyboard users without showing it on every mouse click:

:focus-visible {
  outline: 2px solid var(--ngbr-color-focus);
  outline-offset: 2px;
}

Don't set outline: none without a replacement. Users can't follow a focus they can't see.

How to test it

Put your mouse down. Go through the whole flow with Tab, Enter, Space and the arrow keys, and after each interaction ask where focus went. Open a dialog: is focus inside it? Close it: did focus return to the button? Change route: are you on the new heading? Delete something: are you on a real element, or back at the top?

Most of these bugs show up within a couple of minutes. They're easy to miss because you only see them when you use the app without a pointer.

NgBracket is a set of Angular component packs built to support WCAG 2.2 AA. Its dialogs and drawers trap focus while open and return it to the trigger when they close. Its menus use the arrow keys and return focus to the trigger on Escape. The conformance report lists how each criterion is tested and the known limitations. You can start with the free packs without a card.

Why I built an Angular component library where accessibility isn't a backlog item

Duncan Faulkner — Sun, 05 Jul 2026 17:31:39 +0000

I've been building with Angular for ten years, and in that time I've watched the same thing happen on nearly every project. A component gets built, it works with a mouse, it ships. Accessibility — keyboard support, focus, ARIA, contrast, the screen-reader story — becomes a line in the backlog called something like "a11y pass". And that ticket sits there. It gets groomed, re-estimated, pulled into a sprint, bumped out of the sprint, and eventually closed as "we'll come back to it." We never came back to it.

For a long time I thought that was a discipline problem. If we just cared more, tested more, remembered more, we'd get it right. I don't believe that anymore. Accessibility keeps losing the race to the deadline not because people don't care, but because it's genuinely hard to hold in your head while you're also wrangling state, layout, data and a ticket that was due yesterday. You cannot fix a systemic problem with individual willpower. You fix it by changing the default.

That realisation is the whole reason I built what I built. This is the story of the problem I was actually trying to solve, and how I went about it.

The problem isn't "not enough components"

Let me be clear about what I was not trying to do, because it matters. I wasn't trying to make another component library. There are plenty. A few new ones have appeared just in the last few months, and they're perfectly good — nicely styled, well documented, quick to drop in.

But open the accessibility story on almost any of them and it's the same shape every time: a compliance checkbox, bolted on near the end, covering the third of WCAG that an automated tool can see. aria-label is present, contrast is fine on the light theme, AXE is green. And then you drive it with a keyboard and the dialog swallows your focus, the custom select doesn't respond to arrow keys, the chart is a blank rectangle to a screen reader, and the dark theme quietly fails contrast because nobody checked.

That's the gap. It's not a shortage of components — it's that in almost every library, accessibility is a feature you're expected to finish yourself, and modern Angular is something the library will get to eventually. I didn't want to add to the pile of components. I wanted to close that gap.

So I made two bets, and the whole thing is built on them.

Bet one: accessibility is a first-class citizen, not a compliance pass

The rule I set myself is simple to state and annoying to keep: no component ships until it works by keyboard and its accessibility tree is right. Not “until AXE is green” — AXE is a regression net for the easy third, and I run it in CI on every component, but it is not the test. The test is a human putting the mouse down and driving the whole thing with Tab, Enter, Space and arrows, then checking the accessibility tree — the roles, names and states a screen reader announces — against what’s on screen. (Hands-on NVDA/VoiceOver listening is the gate I’m adding next.)

In practice that meant solving, once and properly, all the things that normally get skipped:

Focus management as a discipline — trap it in dialogs and drawers, restore it to the trigger on close, move it to the heading on route change, send it somewhere sane after you delete the row it was sitting on. One position, always accounted for.
State that's communicated, not just coloured — aria-invalid and aria-describedby wiring errors to fields, role="alert" so they announce, live regions that actually exist in the DOM before the text arrives so a screen reader speaks them.
The hardest case, data visualisation — every chart is keyboard-navigable and carries a visually-hidden data table behind the SVG as the screen-reader source of truth, because "this picture holds information that exists nowhere else" is the single biggest blind spot in automated testing. (There's even optional audio sonification for trends, which was two weeks of my life and worth every day.)
Contrast that survives theming — every colour is a token that re-tones for dark mode and holds AA on both surfaces, verified with an automated contrast pass across every component in light and dark, not eyeballed once on white.

None of that is exotic. It's all well-understood. The point was never to invent new accessibility techniques — it was to do the known-correct thing every single time, so that the person consuming the library never has to file that "a11y pass" ticket, because it's already done.

Bet two: signals-first, because reactive accessibility is better accessibility

The second bet is that this had to be built the modern Angular way — and not for fashion. Standalone components, signals, OnPush everywhere, Material 3 tokens, strict TypeScript, zero NgModules.

Signals aren't just a nicer state primitive here; they turn out to make accessibility easier to get right. When your aria-live announcement, your aria-invalid state, your aria-current and your focus targets are all derived from signals, the accessible state can't drift out of sync with the visual state — they're computed from the same source. Reactive accessibility is more correct accessibility, almost for free. Building on the old change-detection model, you're forever remembering to keep two representations in step. With signals you compute one and both fall out of it.

It also means the library is built the way you're already building in Angular v20+ — so it drops into a modern app without dragging a NgModule-era mental model back in with it. A component library that fights your architecture isn't saving you time.

How I actually went about it

Two bets are easy to write on a slide. Holding them across a real, sellable product took some machinery:

AXE wired into CI as the automated floor, plus a structural accessibility test suite — the regression net for the third that tools can catch, so nothing slips backwards.
A browser-driven contrast harness that walks every component in both themes and fails the build on a single AA violation. That's how I know dark mode holds, rather than hoping.
A token architecture where every surface, text and semantic colour chains through shared design tokens, so theming and dark-mode contrast cascade instead of being re-hardcoded per component.
Dogfooding, relentlessly. I built the marketing site itself, its FAQ, and three complete example apps — an admin dashboard, a storefront, and a booking diary — entirely out of the packs. If a component was awkward to use or quietly inaccessible, I found out by living in it, not by reading my own docs.

Eight packs, a hundred-and-six components, all held to the same line. Built solo, which is terrifying to admit and also exactly why the defaults had to carry the weight — I can't manually re-check accessibility on a hundred components by hand every release, so it had to be baked in and enforced by tooling.

Why I'm banging this drum

I'm writing this partly because the space is getting busier, and I think the distinction is worth being loud about. More component libraries is good for Angular. But "accessible by default" and "modern by default" are not the headline feature on most of them — they're the footnote. For me they're the entire product. If a green CI check is going to tell you the truth about whether a real person can use what you shipped, the two-thirds that automated tools can't see have to already be handled. That's the thing I built, and it's the thing I'll keep making noise about.

If accessibility is the part of your build that always loses the race to the deadline — the ticket that never gets picked up — that's precisely the problem this is meant to take off your plate.

And it's not finished. Eight packs is where it starts, not where it stops — there are more in the pipeline, on a steady cadence, each held to the same line. Which is also where you come in: I'd genuinely rather build the components you're about to write by hand than guess. So if there's a widget you keep re-implementing, a pack you wish existed, or a gnarly accessibility case you've never seen a library get right — tell me. A lot of what's here started as exactly that kind of "someone should just build this properly" itch, and I'm very open to the next one being yours.

I got tired of watching accessibility lose the race, so I built the defaults instead. NgBracket is a set of Angular component packs — 8 packs, 106 components — where WCAG AA, AXE-passing, keyboard and screen-reader support are the baseline, and everything is signals-first, standalone, OnPush, Material 3 themeable, zero NgModules. We're launching soon; join the waiting list for early access.

axe passes but the component is still unusable: five bugs automated tools can't catch

Duncan Faulkner — Thu, 02 Jul 2026 07:10:33 +0000

A green accessibility report is easy to trust. The CI check passes, Lighthouse says 100 and the axe panel shows no violations. You ship it, and a person using a screen reader reaches your component and can't use it.

I've shipped components like that more than once. What I learned is that automated accessibility testing checks whether your HTML is well-formed. It doesn't check whether your interface is usable. Users get stuck in the gap between those two questions.

axe is very good, and you should run it in CI if you don't already. It works by inspecting a snapshot of the DOM against a set of rules. It can see that an attribute is present. It can't see whether the attribute is true, whether the order of things makes sense, or whether anything happens when you press a key. It catches roughly a third of WCAG issues. A person has to check the rest.

Here are five components that all pass axe.

1. The modal that drops your focus

A dialog opens, you confirm, it closes. axe has no complaints: role="dialog", aria-modal, a labelled heading, focus trapped while it's open. All correct.

confirm() {
  this.save();
  this.open.set(false); // ✅ AXE passes. ❌ focus just fell to <body>.
}

A keyboard user sees the dialog close and their focus land on <body>, at the top of the page. They've lost their place and have to Tab back through the whole UI. axe can't catch this. Where focus goes after a state change is a question about time, and the DOM snapshot doesn't hold it.

The fix is to remember the trigger and return focus to it:

private trigger: HTMLElement | null = null;

openDialog() {
  this.trigger = this.doc.activeElement as HTMLElement;
  this.open.set(true);
}
close() {
  this.open.set(false);
  this.trigger?.focus(); // put them back where they were
}

2. The error you can only see if you can see

A form field fails validation and a red border appears. axe checks that the label is present and the border colour has enough contrast. Both are fine.

But colour is the only signal that something went wrong. Some colour-blind users won't see it. A screen-reader user hears nothing, because the message was never tied to the field or announced:

<!-- passes AXE, communicates nothing -->
<input formControlName="email" class="error">
<p class="error-text">Enter a valid email</p>

Nothing connects that <p> to the input, and nothing tells assistive technology it appeared. The fix is to make the error programmatic:

<input formControlName="email"
       [attr.aria-invalid]="showError()"
       [attr.aria-describedby]="showError() ? 'email-error' : null">
@if (showError()) {
  <p id="email-error" role="alert">Enter a valid email.</p>
}

aria-invalid says the field has an error, aria-describedby ties the explanation to it, and role="alert" announces it when it renders. axe won't ask for any of the three. It only knows the label exists.

3. The toggle that looks operable but does nothing

The ARIA here is correct:

@Component({
  host: {
    'role': 'switch',
    '[attr.aria-checked]': 'checked()',
    'tabindex': '0',
    // …no keyboard handler.
  },
})

axe sees a valid switch with a valid aria-checked state and a tabindex. It can't know that pressing Space does nothing. Finding that out means running the control, and axe only reads it. A mouse user can toggle it. A keyboard user can focus it and then can't change it.

host: {
  'role': 'switch',
  '[attr.aria-checked]': 'checked()',
  'tabindex': '0',
  '(keydown.space)': 'toggle(); $event.preventDefault()',
  '(keydown.enter)': 'toggle()',
}

A better option is a native <button> with aria-pressed for the state. A native button handles Space and Enter itself, so it can't have this bug.

4. The live region that never speaks

You add an aria-live region that says "12 results" after filtering, like this:

@if (announcement()) {
  <p aria-live="polite">{{ announcement() }}</p>
}

axe sees a valid live region. But screen readers only announce changes to a live region that was already in the DOM when the change happened. Here the @if adds the element and its text at the same moment, so nothing is announced. The region has to exist empty first and then receive the text:

<p class="sr-only" aria-live="polite">{{ announcement() }}</p>

Or use the CDK's LiveAnnouncer, which keeps a persistent region for you:

private announcer = inject(LiveAnnouncer);
this.announcer.announce(`${count} results`, 'polite');

This is my favourite example, because the broken version looks more correct than the one that works. A tool can't tell them apart. A screen reader tells you straight away.

5. The chart a screen reader can't read

You render an SVG line chart. Contrast meets AA, there's a <title>, and axe passes. To a screen-reader user it's an empty image. SVG internals aren't exposed as data, and no automated rule can say "this picture holds information that appears nowhere else on the page".

The fix is to give the same data in a form assistive technology can read, such as a visually hidden table behind the chart:

<figure>
  <svg aria-hidden="true">…</svg>
  <table class="sr-only">
    <caption>Monthly revenue, Jan–Dec</caption>
    <tr><th>Month</th><th>Revenue</th></tr>
    <!-- one row per point -->
  </table>
</figure>

This is the biggest blind spot in automated testing. It's also why charts are among the hardest things to make accessible on the front end.

What to test by hand

In all five cases axe was right: the HTML was well-formed. Each bug was in something a snapshot can't see: order, interaction, timing or meaning.

So keep axe in CI. It's a good regression check for the third of issues it covers, and it's free. Then add two manual checks, which take a couple of minutes:

Put the mouse down and Tab through the page. Can you reach and operate everything? Does focus go somewhere sensible after each action?
Turn on a screen reader, either VoiceOver (⌘+F5) or NVDA, and listen. Does what you hear match what's on screen?

Those two checks cover a lot of what axe can't. If you only run the automated check, you know your HTML is tidy, but not whether people can use what you built.

I built NgBracket because of this gap. It's a set of Angular component packs built to support WCAG 2.2 AA. Every documented component is checked with axe in CI, I test each new component with the keyboard, and a suite of automated NVDA tests runs against the demo app. The conformance report lists how each criterion is tested and the known limitations. You can start with the free packs without a card.

Introduction to Vitest and Angular

Duncan Faulkner — Sun, 13 Oct 2024 21:49:59 +0000

The Angular team deprecated Karma a few versions ago and are currently working on ways to provide an alternative 3rd party unit testing frameworks. Currently the options talked about so far are Web Test Runner (likely to be the default), this is a browser based unit test runner similar in many ways to Karma. The other option being discussed is Jest, this can be installed now but can be a little tricky sometimes to get set up and some known issues when Angular is set up to use ES builds (the default in Angular 18 onward).

The Angular team are looking at using the CLI for the installation process of these unit testing frameworks, similar to when selecting a CSS framework when creating a new project. This is all still very early on in the development cycle and may be a little way off before it becomes developer preview (currently still experimental) and no mention (as yet) of how this would work with an existing project.

Now that newer versions of Angular use Vite as a development build server and the default in Angular 18, it is now possible to use Vitest in our Angular projects. The installation process is straight forward to set up and feels less problematic than setting up Jest from my recent experience. The great news here is that Vitest has a similar syntax to Karma and Jest, so the learning curve should be fairly small.

In this post I'm going to walk through setting up and configuring Vitest in an Angular 18 application and replacing Karma . I won't be writing unit tests in this post, I'll leave that for another post, this post is about setting up Angular to use Vitest.

I'm going to start a new project for this post but this will also work on an existing project.

In a directory type the following in the terminal:

ng new my-vitest-app  && cd my-vitest-app && npm i

This will create a new Angular application called my-vitest-app, it'll change into that directory and then run npm install with our application created we can now remove Karma.

From the terminal, type:

npm uninstall karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter

We don't need to uninstall @types/jasmine and jasmine-core as Vitest uses Jasmine under the hood, we can use it and describe from Jasmine so we don't need to import anything in our test files. It is possible to use it and describe from Vitest but in doing so we won't be able to use functions like fakeAysnc in our unit tests.

The easiest way to get Vitest installed in our project is to use a plugin and AnalogJS has just what we need to setup and configure Vitest for us.

From the terminal type:

npm i @analogjs/platform -D

Followed by:

ng g @analogjs/platform:setup-vitest --project my-vitest-app

Once complete the following files will be generated:

// vite.config.mts
/// <reference types="vitest" />
import angular from '@analogjs/vite-plugin-angular';
import { defineConfig } from 'vite';

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  return {
    plugins: [
      angular(),
    ],
    test: {
      globals: true,
      environment: 'jsdom',
      setupFiles: ['src/test-setup.ts'],
      include: ['**/*.spec.ts'],
      reporters: ['default'],
    },
    define: {
      'import.meta.vitest': mode !== 'production',
    },
  };
});

vite.config.mts will be in the root of the project, this sets up the configuration for Vitest, what environment to use, the default is jsdom, you can change this to happy-dom (you will need to install happy-dom). The test-setup.ts will be in the src directory and this sets up the test environment.

import '@analogjs/vitest-angular/setup-zone';
import {
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting,
} from '@angular/platform-browser-dynamic/testing';
import { getTestBed } from '@angular/core/testing';

getTestBed().initTestEnvironment(
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting()
);

If you are using azoneless application then the test-setup.ts will be slightly different:

import '@analogjs/vitest-angular/setup-snapshots';

import {
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting,
} from '@angular/platform-browser-dynamic/testing';
import { getTestBed } from '@angular/core/testing';

getTestBed().initTestEnvironment(
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting()
);

In angular.json the test section will be replaced with:

 "test": {
    "builder": "@analogjs/vitest-angular:test"
 }

And finally the tsconfig.spec.json will be update to:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "types": [
      "jasmine",
      "vitest/globals" // added
    ],
    "target": "es2016" // added
  },
  "include": [
    "src/**/*.spec.ts",
    "src/**/*.d.ts"
  ],
  "files": [
    "src/test-setup.ts" // added
  ]
}

To run Vitest tests we need to change the scripts section, in our applications package.json file add:

{
 // other scripts
 "test" : "vitest"   
}

Using npm run test will run all of our test files our project.

If you don't want to install Volta you can skip this section.

To run Vitest from the terminal we need to install Vitest, we have a couple of options, globally using npm i -g vitest, I tend to use Volta, this is a tool chain manager, similar to Node Version Manager (NVM) but Volta handles other JavaScript tooling other than just Node.

If you currently have a version of node installed, you will need to uninstall this first before install Volta, once Volta is installed we can install multiple versions of node without removing the previous versions.

To install Volta head over to https://volta.sh/ and get the appropriate installer package for your operating system, I'm using Ubuntu and all we need for this is:

# install volta
curl https://get.volta.sh | bash
# install node
volta install node@20.15.0

As a side note, one of the nice features of Volta, is the ability to pin the version of node we are using to our package.json file, meaning that Volta will always select the correct version of Node, this is real handy when working in a team of developers, to pin a version of Node to our package.json file run volta pin node@20.15.0.

With volta and node installed we can now install Vitest:

volta install vitest

With Vitest installed we can run volta ls this will show a list of the tooling that we have installed.

# example listing from Volta
⚡️ Currently active tools:

    Node: v20.15.1 (default)
    Tool binaries available:
        vitest (current @ /home/repo/vitest-app/package.json)

With everything installed we can now run our unit tests, if we want to run a selection of tests (or a specific test) then we need to use the terminal and pass in an additional parameter, this parameter will run any test file that contains this parameter.

# run a range of unit tests
vitest dashboard

We can also specify a file, this will only run a unit test that matches the file name, note that this doesn't support regex or glob patterns.

# run a specific unit test
vitest app.component

The above will run the unit tests and watch for changes, to run the unit test once and not watch for changes we can change the command to:

# run unit test(s) once then stop
vitest run [optionally specify an additional parameter]

If we want to run our unit tests in a CI environment we don't need for them to be in watch mode, so add a test:ci to the script section of the package.json file.

{
 // other scripts
 "test" : "vitest",
 "test:ci" : "vitest run"
}

We need to set up our build pipelines to run our tests, setting up build pipelines is out of scope for this post, so I will assume you know how to do this, if not they are plenty of posts on how to do this.

The next part I want to cover is code coverage, so we've written our unit tests for our various features in our project, but have we written enough? Have we covered the important parts that need testing? This is where code coverage comes to the rescue. Code Coverage tell us how much of our feature is covered by unit tests, whether we've missed a path, for example we've covered the if condition but not the else condition.

Let's add a new script to the scripts section of our package.json file.

{
// other scripts    
"coverage":"vitest run --coverage"
}

With this we can run npm run coverage locally and will create a coverage directory for us in the root of the project and we'll get a table of files along with their code coverage:

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	100	100	100	100
app.component.ts	100	100	100	100

When we run this it might prompt to install a supporting package this can be either coverage-v8 (the default) or coverage-instanbul package, if not we can install them manually using:

# For v8
npm i -D @vitest/coverage-v8

# For istanbul
npm i -D @vitest/coverage-istanbul

We can set the provider type in the coverage section in the vite.config.mts file:

export default defineConfig(({ mode }) => {
  return {
    plugins: [angular()],
    test: {
      globals: true,
      environment: "jsdom",
      setupFiles: ["src/test-setup.ts"],
      include: ["**/*.spec.ts"],
      reporters: ["default"],
      coverage: {
        provider: "v8",
        reporter: ["text", "json", "html"],
      },
    },
    define: {
      "import.meta.vitest": mode !== "production",
    },
  };
});

To run code coverage in our CI environment we need to adjust our test:ci script to include a reporter, here I've used junit and junit.xml and there is a handy plugin for Azure Devops to read the junit.xml file which will import the file and create a nice dashboard for us.

script:{
// other scripts
"test:ci": "vitest run --reporter=default --reporter=junit --outputFile=reports/junit.xml",
}

In Azure devops we can add the PublishTestResults task in our build pipelines and would have the task run after our unit tests have completed.

When we run our unit tests the results will be displayed in the terminal (unless running in a CI environment), but if you prefer to see the results in a browser this is also possible, first we need to install the ui tooling:

npm i @vitest/ui

You will need to match the version of @vitest/ui to the same version of vitest installed on your system, once installed we can start it by running vitest --ui from the terminal, if we add the html to the reporters array in our vite.config.ts file, this will create an html directory with all the files.

export default defineConfig(({ mode }) => {
  return {
    plugins: [angular()],
    test: {
      globals: true,
      environment: "jsdom",
      setupFiles: ["src/test-setup.ts"],
      include: ["**/*.spec.ts"],
      reporters: ["default", "html"], // add html into this array.
      coverage: {
        provider: "v8",
        reporter: ["text", "json", "html"],
      },
    },
    define: {
      "import.meta.vitest": mode !== "production",
    },
  };
});

Conclusion

In this post we looked at installing and setting up Vitest, a unit test runner in for Angular applications based on Vite, we also added code coverage to our test runs to see how much code coverage our unit tests cover, we also learnt how we can set this up in our CI in Azure Devops.

Using Mat-Icon Component – Part Two

Duncan Faulkner — Mon, 27 Jan 2020 13:27:00 +0000

Blog Post #002

Duncan Faulkner – January 2020

I hadn’t intended to write about this just yet, but I got a chance to investigate this sooner than I had thought. I was refactoring part of a project that was using the Mat-Icon component, with an icon.module.ts file as I’d discussed in the previous post.

I wanted to see if I could improve on the code and reduce the amount of repeated code by iterating over a file and registering the icons.

I started with a JSON file and populated it with some image names and added the HttpClientModule to use an http.get() method to read the JSON file. All good so far, the file is reading and looping with image names being returned and passed into the matIconRegistery.addSvgIcon() method.

I thought I might get some issues, but it all seemed to work fine, except the application was erroring, the issue was that the application was loading before the call to the JSON file had returned with the results, so even though I was getting images and registering icons, the app had already tried to use the icons and they weren’t there at that point, and the images were being returned after the app had started.

OK, so may be this is a timing issue and it doesn’t work in the icon.module.ts file, so I moved code to the app.component.ts file. Nope, the results were the same. This was not the result I was expecting and it was a little odd because the icon.module.ts file was loading images before.

I’m going to revisit this at a later date, as I would like to understand what the issue is and why it was behaving the way it did, my guess is it has something to do with the http.get() request and the timing around that.

But as I needed to get this refactoring completed I needed to look for another solution.

After a bit of research I found an answer and that was to create a service to handle the iterating and registering of icons. Instead of a JSON file to store a list of images the solution was an enum, with a key value structure.

export enum Icons {
    add = 'add',
    power = 'power',
    save = 'save'
}

To keep things simple I’ve made the key and the image name the same.

The service is quite simple:

// imports
import { Icons } from '../image.enum';

@Injectable({ providedIn: 'root'})
export class IconService {
  constructor(
     private matIconRegistry: MatIconRegistry,
     private sanitizer: Domsanitizer
){}

registerIcons(): void {
   this.load(Object.values(Icons), 'assets/images/icons');
}

private load(key: string[], url: string): void {
   key.forEach(icon => {
     this.matIconRegistry.addSvgIcon(
       icon, 
       this.sanitizer.bypassSecurityTrustResourceUrl(`${url}/${icon}.svg`)
   ); 
 });
 }
}

And on the app.component.ts file call the registerIcons() function.

// imports
import { IconService } from './icon.service';

export class AppComponent implements OnInit {
   constructor(private iconService: IconService) {
      this.iconService.registerIcons();
   }

}

And that’s it, not what I had in mind when I started this, but it does deliver what I wanted to do, and that was to reduce the amount of code to register icons. Though I guess the enum could get pretty lengthy if there are a lot of images.

I have to thank Stefanos Kouroupis -dev.to – for his article and code on this as I wouldn’t have thought about using a service for this and this has changed my thinking. I wanted to include here it as a follow up to my previous post for completeness, you can see his full article here https://dev.to/elasticrash/using-custom-made-svg-icons-through-the-angular-material-library-2pif.

I will add a github repo of the code in a day or two.

Original article published at: https://anglebrackets.io/index.php/2020/01/25/using-mat-icon-component-part-two/

Angular Materials Mat-Icon component

Duncan Faulkner — Thu, 14 Nov 2019 18:34:22 +0000

Using local SVG images.

Blog post #001

Duncan Faulkner - October 2019

When developing an Angular application with Angular Material, there comes a point when we need to add icons on our components, or buttons etc... Angular Material has the Mat-Icon component for doing this. This component works with web fonts like Font-Awesome for instance, simply by adding the name of the image required and an image is displayed.

For example:

<mat-icon>home</mat-icon>

Note: Requires Angular application and Angular Material is installed/configured and a reference to a web font like Font-Awesome library is all set up

But what about if you have custom icons that are not part of a web font? And would like to makes changes to the icon, for example: change the colour on hover or on a specific condition at run time?

In a recent project I had a bespoke set of SVG icons, the Angular web application was to be installed on a server that didn't have access to the internet, so the images had to be local. I wanted to use the Mat-Icon component out of the box (in an early version of the project I had a custom icon component). I still wanted to be able to change the colours of the icons at various stages throughout the application based on certain conditions as well as on hover. This post covers how I achieved that.

SVG Icons

There are a number of different ways to register an icon with the Mat-Icon component, this post discusses addSvgIcon, the others are addSvgIconInNamespace, addSvgIconLiteral or addSvgIconLiteralInNamespace and are all methods of MatIconRegistry and I might cover these in more detail in a future post.

Setting up an Angular project

Note In this post, I'm not going to step through the creation of an Angular application as there are so many already online. Plus I tend to create Nx workspaces for all my Angular projects as I prefer this project layout. I plan to do a blog post on this very soon, for the moment though see Getting started with Narwhal's Nx Workspaces.

In the newly created Angular project, create a shared directory and add a new file named material.module.ts. I like to separate Angular Material imports into their own module, I also create a separate module for other 3rd party components, just makes it easier to import later, especially using the Nx workspace layout and feature folders.

In the material.module.ts

// Material Module example.
// All other Angular Material component imports here
// but the important ones are...
import {MatIconModule, MatIconRegistry} from '@angular/material/icon';

@NgModule({
    declarations: [],
    imports: [
    // Other material imports removed for brevity,
    MatIconModule],
    exports: [
    // Other material exports removed for brevity,
    MatIconModule, MatIconRegistry
    ],
    entryComponents: [],
    providers: [MatIconRegistry]
})
export  class  MaterialModule  {}

MatIconModule is the module for the component, and the MatIconRegistry is a service to register and display icons. Add a reference to the material.module.ts in the app.module.ts. Don't forget to export it as well, otherwise it won't be available and Angular will not know anything about the Angular Material components.

// Include the material module in app.module.ts
import  {  BrowserModule  }  from  '@angular/platform-browser';
import  {  NgModule  }  from  '@angular/core';
import  {  AppComponent  }  from  './app.component';
import  {  BrowserAnimationsModule  }  from  '@angular/platform-browser/animations';
import  {  MaterialModule  }  from  './shared/material.module';

@NgModule({
declarations:  [AppComponent],
imports:  [BrowserModule,  BrowserAnimationsModule,  MaterialModule],
providers:  [],
bootstrap:  [AppComponent]
})
export  class  AppModule  {}

Now we have the Angular Material components set up and configured we need to register the icons, before we can use them. For the moment we are just going to add these to the app.component.ts to get up and running, we'll look at a better method later on.

// First Example
@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss']
})
export class AppComponent {
    constructor (
        private matIconRegistry: MatIconRegistery
    ){
    this.matIconRegistry.addSvgIcon('home','assets/img/icon/home.svg');
    this.matIconRegistry.addSvgIcon('add','assets/img/icon/add.svg');
    }
    // or we could do this, and chain the addsvgIcon methods.
    // we'll use this method going forward in this post
    // {
    //      this.matIconRegistry.addSvgIcon('home','assets/img/icon/home.svg')
    //      .addSvgIcon('add','assets/img/icon/add.svg');
    // }
}

Add this to the app.component.html page, we'll discuss this in more detail in a bit.

<!-- First HTML example -->
<div>
    <mat-icon svgIcon="home"></mat-icon>
    <mat-icon svgIcon="add"></mat-icon>
</div>

At this point we are not going to see much in the browser as we have an issue with the image URL. If you open the browsers console section, you will see the following error:

Error: unsafe value used in a resource URL context.

So what does this error mean? A brief explanation from the Angular Material website says:

To prevent an Cross Site Scripting (XSS), SVG URL's and HTML strings passed to MatIconRegistry must be marked as trusted by the Angular's DomSanitizer service. Icons are fetched via XmlHttpRequest and must have their URL's on the same domain as the containing page or configured to allow cross-domain access.

So lets add the DomSanitizer and fix this issue.

// Second Example - with the DomSanitizer
@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss']
})
export class AppComponent {
    constructor (
        private domSanitizer: DomSanitizer, 
        private matIconRegistry: MatIconRegistery
    ){
    this.matIconRegistry
    .addSvgIcon('home',this.domSanitizer.bypassSecurityTrustResourceUrl('assets/img/icon/home.svg')
    .addSvgIcon('add',this.domSanitizer.bypassSecurityTrustResourceUrl('assets/img/icon/add.svg')
    // add other icons here....;
    }
}

The call to bypassSecurityTrustResourceUrl takes a URL as a parameter and sanitizes it so that an attacker cannot inject a 'JavaScript:` URL for example, see official documentation on DomSanitizer.
Now that we have this in place we should now see two icons in the browser.

If we have a lot of icons to add this means lots of typing and lots of repetitive code, so lets refactor this some more. Start by removing all of this code (including the constructor) from the app.component.ts. This shouldn't really be in the app.component.ts file. Lets create another new module in the shared directory and call it icon.module.ts and then add the following:

typescript // Third Example - icon module import { NgModule } from '@angular/core'; import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser'; import { MaterialModule } from '../shared/material.module'; import { MatIconRegistry } from '@angular/material/icon'; @NgModule({ declarations: [], imports: [MaterialModule], exports: [], providers: [] }) export class IconModule { private path: string = '../../assets/images'; // change this constructor( private domSanitizer: DomSanitizer, public matIconRegistry: MatIconRegistry ) { this.matIconRegistry .addSvgIcon('home', this.setPath(${this.path}/home.svg)) .addSvgIcon('add', this.setPath(${this.path}/file-plus.svg)); } private setPath(url: string): SafeResourceUrl { return this.domSanitizer.bypassSecurityTrustResourceUrl(url); } }
Overall, that's not too bad, we are only writing out the domSanitizer code once in the private method but more importantly, all the code is out of the app.component.ts file and is now a self contained module. If there are a lot of icons to add then this file will get a bit long, but the typing has gotten shorter (well, a little shorter at least). You could change the constructorto iterate through a .json file of image names, the path wouldn't change and could be a const, which would only mean maintaining a .json file with any new images. I might look at doing that in a follow up post.

Note: Don't forget to add this new icon.module.ts to the app.module.ts otherwise it won't work.

Using the Mat-Icon component

So how do we use the mat-icon component? As seen earlier in this post we add the following code to our app.components.html page.

`html

`
This is a very simple example is showing how to put a home and an add icon on a page/component. This is not too dissimilar to how we would use this component with web fonts, but we are now using the svgIcon input property. The value we give to this input is the first parameter used in our call to register the .addSvgIcon('home', ...) in this case home.

Now we have an icon in place, how do we change the colour of the icon when someone hovers over it for example.

Change the icon colour

A Home icon.
Example icon copy this into a file with the SVG extension.
svg <svg version="1.1" width="24" height="24" viewBox="0 0 24 24"><path d="M10,20V14H14V20H19V12H22L12,3L2,12H5V20H10Z" fill="#00FFFF" /></svg>
In the above XML, I've removed all the namespaces etc... The main part here is the fill="#00FFFF" this sets the colour for the image, in this case to AquaMarine.

If the fill="#00..." property is not there and you want a different colour to the default black, then you can add it to the path as above, it's optional.

I usually add the fill property and set it to white and then change them in SCSS as and when required (but because this example had a white the background I used another colour).

`html
!<-- Second HTML example -->

!&lt;-- other code omitted for brevity --&gt; 
<a>

</a>

`
Add a class to the mat-icon html tag, as above and then add the SCSS, for the class. So when a user hovers over the button the colour of the icon changes.

scss .btn-icon { &:hover { path { fill: rgba(#00ffff, 1); } } }
Note One thing I did forget to add to the app.component.ts above, was the following line:
encapsulation: ViewEncapsulation.None, without this then the hover affect doesn't work.

typescript @Component({ selector: 'mat-icon-demo-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], encapsulation: ViewEncapsulation.None, }) export class AppComponent { title = 'mat-icon-demo'; }
Enjoy!

There is a github repo for this blog post at:
https://github.com/Anglebrackets-io/mat-icon-demo