Cookies concent notice

This site uses cookies from Google to deliver its services and to analyze traffic.
Learn more
Skip to main content
This site is no longer updated.Head to Angular.devHome
/

This is the archived documentation for Angular v17. Please visit angular.dev to see this page for the current version of Angular.

RouterLinkWithHref

When applied to an element in a template, makes that element a link that initiates navigation to a route. Navigation opens one or more routed components in one or more <router-outlet> locations on the page.

See more...

Exported from

Selectors

Properties

Property Description
href: string | null

Represents an href attribute value applied to a host element, when a host element is <a>. For other tags, the value is null.

@Input()
target?: string

Represents the target attribute on a host element. This is only used when the host element is an <a> tag.

@Input()
queryParams?: Params | null

Passed to Router#createUrlTree as part of the UrlCreationOptions.

See also:

@Input()
fragment?: string

Passed to Router#createUrlTree as part of the UrlCreationOptions.

See also:

@Input()
queryParamsHandling?: QueryParamsHandling | null

Passed to Router#createUrlTree as part of the UrlCreationOptions.

See also:

@Input()
state?: { [k: string]: any; }

Passed to Router#navigateByUrl as part of the NavigationBehaviorOptions.

See also:

@Input()
info?: unknown

Passed to Router#navigateByUrl as part of the NavigationBehaviorOptions.

See also:

@Input()
relativeTo?: ActivatedRoute | null

Passed to Router#createUrlTree as part of the UrlCreationOptions. Specify a value here when you do not want to use the default value for routerLink, which is the current activated route. Note that a value of undefined here will use the routerLink default.

See also:

@Input('{ transform: booleanAttribute }')
preserveFragment: boolean

Passed to Router#createUrlTree as part of the UrlCreationOptions.

See also:

@Input('{ transform: booleanAttribute }')
skipLocationChange: boolean

Passed to Router#navigateByUrl as part of the NavigationBehaviorOptions.

See also:

@Input('{ transform: booleanAttribute }')
replaceUrl: boolean

Passed to Router#navigateByUrl as part of the NavigationBehaviorOptions.

See also:

@Input()
routerLink: string | any[]
Write-Only

Commands to pass to Router#createUrlTree.

  • array: commands to pass to Router#createUrlTree.
  • string: shorthand for array of commands with just the string, i.e. ['/route']
  • null|undefined: effectively disables the routerLink

See also:

urlTree: UrlTree | null Read-Only

Description

Given a route configuration [{ path: 'user/:name', component: UserCmp }], the following creates a static link to the route: <a routerLink="/user/bob">link to user component</a>

You can use dynamic values to generate the link. For a dynamic link, pass an array of path segments, followed by the params for each segment. For example, ['/team', teamId, 'user', userName, {details: true}] generates a link to /team/11/user/bob;details=true.

Multiple static segments can be merged into one term and combined with dynamic segments. For example, ['/team/11/user', userName, {details: true}]

The input that you provide to the link is treated as a delta to the current URL. For instance, suppose the current URL is /user/(box//aux:team). The link <a [routerLink]="['/user/jim']">Jim</a> creates the URL /user/(jim//aux:team). See Router#createUrlTree for more information.

You can use absolute or relative paths in a link, set query parameters, control how parameters are handled, and keep a history of navigation states.

The first segment name can be prepended with /, ./, or ../.

  • If the first segment begins with /, the router looks up the route from the root of the app.
  • If the first segment begins with ./, or doesn't begin with a slash, the router looks in the children of the current activated route.
  • If the first segment begins with ../, the router goes up one level in the route tree.

Setting and handling query params and fragments

The following link adds a query parameter and a fragment to the generated URL:

      
      <a [routerLink]="['/user/bob']" [queryParams]="{debug: true}" fragment="education">
  link to user component
</a>
    

By default, the directive constructs the new URL using the given query parameters. The example generates the link: /user/bob?debug=true#education.

You can instruct the directive to handle query parameters differently by specifying the queryParamsHandling option in the link. Allowed values are:

  • 'merge': Merge the given queryParams into the current query params.
  • 'preserve': Preserve the current query params.

For example:

      
      <a [routerLink]="['/user/bob']" [queryParams]="{debug: true}" queryParamsHandling="merge">
  link to user component
</a>
    

See UrlCreationOptions#queryParamsHandling.

Preserving navigation history

You can provide a state value to be persisted to the browser's History.state property. For example:

      
      <a [routerLink]="['/user/bob']" [state]="{tracingId: 123}">
  link to user component
</a>
    

Use Router#getCurrentNavigation to retrieve a saved navigation-state value. For example, to capture the tracingId during the NavigationStart event:

      
      // Get NavigationStart events
router.events.pipe(filter(e => e instanceof NavigationStart)).subscribe(e => {
  const navigation = router.getCurrentNavigation();
  tracingService.trace({id: navigation.extras.state.tracingId});
});