Location - Angular

A service that applications can use to interact with a browser's URL.

API

class Location implements OnDestroy {
  constructor(locationStrategy: LocationStrategy): Location;
  path(includeHash?: boolean): string;
  getState(): unknown;
  isCurrentPathEqualTo(path: string, query?: string): boolean;
  normalize(url: string): string;
  prepareExternalUrl(url: string): string;
  go(path: string, query?: string, state?: any): void;
  replaceState(path: string, query?: string, state?: any): void;
  forward(): void;
  back(): void;
  historyGo(relativePosition?: number): void;
  onUrlChange(fn: (url: string, state: unknown) => void): VoidFunction;
  subscribe(onNext: (value: PopStateEvent) => void, onThrow?: ((exception: any) => void) | null | undefined, onReturn?: (() => void) | null | undefined): SubscriptionLike;
  static normalizeQueryParams: (params: string) => string;
  static joinWithSlash: (start: string, end: string) => string;
  static stripTrailingSlash: (url: string) => string;
}

constructor

Location

@paramlocationStrategyLocationStrategy

@returnsLocation

path

string

Normalizes the URL path for this location.

@paramincludeHashboolean

True to include an anchor fragment in the path.

@returnsstring

getState

unknown

Reports the current state of the location history.

@returnsunknown

isCurrentPathEqualTo

boolean

Normalizes the given path and compares to the current normalized path.

@parampathstring

The given URL path.

@paramquerystring

Query parameters.

@returnsboolean

normalize

string

Normalizes a URL path by stripping any trailing slashes.

@paramurlstring

String representing a URL.

@returnsstring

prepareExternalUrl

string

Normalizes an external URL path. If the given URL doesn't begin with a leading slash ('/'), adds one before normalizing. Adds a hash if HashLocationStrategy is in use, or the APP_BASE_HREF if the PathLocationStrategy is in use.

@paramurlstring

String representing a URL.

@returnsstring

go

void

Changes the browser's URL to a normalized version of a given URL, and pushes a new item onto the platform's history.

@parampathstring

URL path to normalize.

@paramquerystring

Query parameters.

@paramstateany

Location history state.

@returnsvoid

replaceState

void

Changes the browser's URL to a normalized version of the given URL, and replaces the top item on the platform's history stack.

@parampathstring

URL path to normalize.

@paramquerystring

Query parameters.

@paramstateany

Location history state.

@returnsvoid

forward

void

Navigates forward in the platform's history.

@returnsvoid

back

void

Navigates back in the platform's history.

@returnsvoid

historyGo

void

Navigate to a specific page from session history, identified by its relative position to the current page.

@paramrelativePositionnumber

Position of the target page in the history relative to the current page. A negative value moves backwards, a positive value moves forwards, e.g. location.historyGo(2) moves forward two pages and location.historyGo(-2) moves back two pages. When we try to go beyond what's stored in the history session, we stay in the current page. Same behaviour occurs when relativePosition equals 0.

@returnsvoid

onUrlChange

VoidFunction

Registers a URL change listener. Use to catch updates performed by the Angular framework that are not detectible through "popstate" or "hashchange" events.

@paramfn(url: string, state: unknown) => void

The change handler function, which take a URL and a location history state.

@returnsVoidFunction

normalizeQueryParams

(params: string) => string

Normalizes URL parameters by prepending with ? if needed.

joinWithSlash

(start: string, end: string) => string

Joins two parts of a URL with a slash if needed.

stripTrailingSlash

(url: string) => string

Removes a trailing slash from a URL string if needed. Looks for the first occurrence of either #, ?, or the end of the line as / characters and removes the trailing slash if one exists.

Description

A service that applications can use to interact with a browser's URL.

Depending on the LocationStrategy used, Location persists to the URL's path or the URL's hash segment.

Usage Notes

It's better to use the Router.navigate() service to trigger route changes. Use Location only if you need to interact with or create normalized URLs outside of routing.

Location is responsible for normalizing the URL against the application's base href. A normalized URL is absolute from the URL host, includes the application's base href, and has no trailing slash:

/my/app/user/123 is normalized
my/app/user/123 is not normalized
/my/app/user/123/ is not normalized

Example

import {Location, LocationStrategy, PathLocationStrategy} from '@angular/common';
import {Component} from '@angular/core';

@Component({
  selector: 'path-location',
  providers: [Location, {provide: LocationStrategy, useClass: PathLocationStrategy}],
  template: `
    <h1>PathLocationStrategy</h1>
    Current URL is: <code>{{ location.path() }}</code
    ><br />
    Normalize: <code>/foo/bar/</code> is: <code>{{ location.normalize('foo/bar') }}</code
    ><br />
  `,
  standalone: false,
})
export class PathLocationComponent {
  location: Location;
  constructor(location: Location) {
    this.location = location;
  }
}