iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use Angular Router’s matcher property when a URL pattern cannot be expressed with the usual path and pathMatch options. A custom UrlMatcher examines URL segments and returns the segments it consumes, optionally exposing extracted values as route parameters. Do not combine matcher with path or pathMatch on the same route.
When to use a custom route matcher
Angular’s standard route syntax handles ordinary static paths, parameterized paths such as users/:id, and wildcard paths. Prefer that configuration when it describes the URL you need: it is simpler to read and maintain. Reach for a custom matcher only when the URL structure or matching rule genuinely exceeds what standard paths can express. Angular cautions that complex matching logic can add navigation-time work and make routing harder to maintain. Angular’s guidance on customizing route behavior discusses that trade-off.
| Approach | Pattern expressiveness | Configuration and maintenance |
|---|---|---|
path / pathMatch |
Suitable for ordinary static, parameterized, and wildcard paths. | Uses standard route configuration; usually the simpler choice. |
matcher |
Supports URL shapes or matching rules that standard path syntax cannot express. | Requires custom code; keep it focused to limit maintenance and navigation-time cost. |
What a UrlMatcher receives and returns
Angular defines the matcher as UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: Route) => UrlMatchResult | null. The arguments are the URL segments being considered, their segment group, and the route configuration. A match returns an object with a consumed array and may include posParams, a mapping from parameter names to UrlSegment values. Return null when the segments do not match; the router can then continue evaluating route configurations.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
See the UrlMatcher API for the function type and the UrlMatchResult API for its result shape.
#1 Best Overall
Build a matcher for a username segment
This example follows Angular’s tutorial: it matches a single segment beginning with @, validates the username portion, consumes that segment, and exposes the username as a positional parameter.
import { UrlMatcher, UrlSegment } from '@angular/router';
export const usernameMatcher: UrlMatcher = (segments) => {
if (segments.length !== 1) {
return null;
}
const match = segments[0].path.match(/^@([w]+)$/);
if (!match) {
return null;
}
return {
consumed: [segments[0]],
posParams: {
username: new UrlSegment(match[1], {})
}
};
};The important details are the early null returns, the consumed segment, and the username value represented as a UrlSegment. The regular expression here is the tutorial’s example rule, not a universal definition of valid usernames. Angular’s complete custom route matching tutorial shows the matcher used in a route configuration and demonstrates making the parameter available as a component input with provideRouter(routes, withComponentInputBinding()).
Register the matcher on a route
Assign the function to the route’s matcher property. The route configuration must not also define path or pathMatch; Angular’s Route API documents that restriction.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →import { Routes } from '@angular/router';
import { ProfileComponent } from './profile.component';
import { usernameMatcher } from './username.matcher';
export const routes: Routes = [
{
matcher: usernameMatcher,
component: ProfileComponent
}
];Order routes by specificity
Angular uses first-match-wins route ordering. Put more specific route configurations before broader ones so a general route does not claim a URL intended for a more specific match. This applies when organizing the full route list, not by adding path to a matcher route. See Angular’s route-definition guidance.
Quick Recap
Rank #3
Check the matcher before relying on it
- Test a URL that should match and confirm the expected segments are consumed.
- Test a URL with the wrong number of segments and one that fails the pattern; both should return
null. - Verify that each extracted parameter is present in
posParamsas aUrlSegment. - Review neighboring route entries to ensure a more specific route appears before a general one.
- Keep the matcher focused on segment recognition; avoid unnecessary work during navigation.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
