Use Angular Router’s matcher route property when a URL pattern cannot be expressed clearly with ordinary path and pathMatch configuration. A custom matcher receives URL segments, the current segment group, and the route configuration; it returns the segments to consume, optional named parameters, or null when the route does not match.
When to use a custom route matcher
Start with standard route syntax for ordinary static URLs, parameters such as :id, and wildcard routes. Use a custom UrlMatcher only when the URL shape or matching rule genuinely exceeds what those patterns can express. A matcher adds code that must be maintained and runs during navigation, so intricate or costly logic can make routing harder to maintain and affect performance. See Angular’s guidance on customizing route behavior.
As an Amazon Associate I earn from qualifying purchases.
| Approach | Best fit | Trade-off |
|---|---|---|
path / pathMatch |
Conventional static, parameterized, or wildcard routes | Simpler route configuration, but limited to the standard pattern syntax |
matcher |
A URL structure or rule standard route syntax cannot express | More expressive, but requires custom logic and ongoing maintenance |
These are alternatives on a route: Angular does not allow matcher to be combined with path or pathMatch on the same route. The UrlMatcher API and Route API document this restriction.
Free tools Windows power users keep installed
One-click scans. No signup required.
How Angular evaluates a matcher
The documented function type is UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: Route) => UrlMatchResult | null. Angular supplies the URL segments being considered, their current segment group, and the route configuration.
#1 Best Overall
- Return
nullif the URL does not satisfy your rule. Angular can then continue evaluating route configurations. - For a match, return an object with
consumed, an array of theUrlSegmentobjects the route matched. - Optionally include
posParams, an object mapping parameter names toUrlSegmentobjects.
The UrlMatchResult API describes these result fields.
Example: match a username prefixed with @
Angular’s custom route matches tutorial demonstrates a matcher that accepts one URL segment beginning with @, checks the username against a pattern, and exposes the part after @ as a named username parameter. The essential matcher shape is:
import { UrlMatcher } from '@angular/router';
export const usernameMatcher: UrlMatcher = (segments) => {
if (segments.length !== 1) {
return null;
}
const match = /^@([a-zA-Z0-9]+)$/.exec(segments[0].path);
if (!match) {
return null;
}
return {
consumed: [segments[0]],
posParams: {
username: segments[0].toString().replace(/^@/, '')
}
};
};Configure the route with the matcher rather than a path:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
const routes = [
{
matcher: usernameMatcher,
component: ProfileComponent
}
];The tutorial’s complete example configures routing with provideRouter(routes, withComponentInputBinding()) and binds the extracted username value to a component input. Use that binding approach when it fits your application; otherwise, read the route parameter through your chosen Angular routing pattern.
Rank #3
Build and register the matcher
- Define a function. Type it as
UrlMatcherif you want TypeScript to check its arguments and return value. - Reject non-matches early. Check segment count and the relevant segment content; return
nullas soon as the required shape fails. - Return the consumed segments. Include the matched
UrlSegmentobjects inconsumed, and add named values underposParamsonly when needed. - Assign it to a route’s
matcherfield. Do not also setpathorpathMatchon that route. - Order routes deliberately. Put more specific configurations before general ones: Angular uses first-match-wins route ordering. See Define routes.
Keep matching logic narrow
Make the matcher answer one routing question: do these segments fit this route, and which segments or parameter values should it expose? Avoid unrelated work or complex computation in the matcher. Keeping it concise makes route behavior easier to inspect and reduces the risk that matching work slows navigation.
Quick Recap
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.
