Help Angular by taking a 1 minute survey!Go to surveyHome
API > @angular/common

Location

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

See more...

      
      class Location {
  static normalizeQueryParams(params: string): string
  static joinWithSlash(start: string, end: string): string
  static stripTrailingSlash(url: string): string
  path(includeHash: boolean = false): string
  isCurrentPathEqualTo(path: string, query: string = ''): boolean
  normalize(url: string): string
  prepareExternalUrl(url: string): string
  go(path: string, query: string = '', state: any = null): void
  replaceState(path: string, query: string = '', state: any = null): void
  forward(): void
  back(): void
  subscribe(onNext: (value: PopStateEvent) => void, onThrow?: (exception: any) => void, onReturn?: () => void): SubscriptionLike
}

Subclasses

Description

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

Static methods

normalizeQueryParams()

Given a string of url parameters, prepend with ? if needed, otherwise return the parameters as is.
static normalizeQueryParams(params: string): string
      
      static normalizeQueryParams(params: string): string
Parameters
params string

String of URL parameters
Returns

string: URL parameters prepended with ? or the parameters as is.

joinWithSlash()

Given 2 parts of a URL, join them with a slash if needed.
static joinWithSlash(start: string, end: string): string
      
      static joinWithSlash(start: string, end: string): string
Parameters
start string

URL string
end string

URL string
Returns

string: Given URL strings joined with a slash, if needed.

stripTrailingSlash()

If URL has a trailing slash, remove it, otherwise return the URL as is. The method looks for the first occurrence of either #, ?, or the end of the line as / characters and removes the trailing slash if one exists.
static stripTrailingSlash(url: string): string
      
      static stripTrailingSlash(url: string): string
Parameters
url string

URL string
Returns

string: Returns a URL string after removing the trailing slash if one exists, otherwise returns the string as is.

Methods

path()

Returns the normalized URL path.
path(includeHash: boolean = false): string
      
      path(includeHash: boolean = false): string
Parameters
includeHash boolean

Whether path has an anchor fragment.

Optional. Default is false.
Returns

string: The normalized URL path.

isCurrentPathEqualTo()

Normalizes the given path and compares to the current normalized path.
isCurrentPathEqualTo(path: string, query: string = ''): boolean
      
      isCurrentPathEqualTo(path: string, query: string = ''): boolean
Parameters
path string

The given URL path
query string

Query parameters

Optional. Default is ''.
Returns

boolean: true if the given URL path is equal to the current normalized path, false otherwise.

normalize()

Given a string representing a URL, returns the URL path after stripping the trailing slashes.
normalize(url: string): string
      
      normalize(url: string): string
Parameters
url string

String representing a URL.
Returns

string: Normalized URL string.

prepareExternalUrl()

Given a string representing a URL, returns the platform-specific external URL path. If the given URL doesn't begin with a leading slash ('/'), this method adds one before normalizing. This method also adds a hash if HashLocationStrategy is used, or the APP_BASE_HREF if the PathLocationStrategy is in use.
prepareExternalUrl(url: string): string
      
      prepareExternalUrl(url: string): string
Parameters
url string

String representing a URL.
Returns

string: A normalized platform-specific URL.

go()

Changes the browsers URL to a normalized version of the given URL, and pushes a new item onto the platform's history.
go(path: string, query: string = '', state: any = null): void
      
      go(path: string, query: string = '', state: any = null): void
Parameters
path string

URL path to normalizze
query string

Query parameters

Optional. Default is ''.
state any

Location history state

Optional. Default is null.
Returns

void

replaceState()

Changes the browser's URL to a normalized version of the given URL, and replaces the top item on the platform's history stack.
replaceState(path: string, query: string = '', state: any = null): void
      
      replaceState(path: string, query: string = '', state: any = null): void
Parameters
path string

URL path to normalizze
query string

Query parameters

Optional. Default is ''.
state any

Location history state

Optional. Default is null.
Returns

void

forward()

Navigates forward in the platform's history.
forward(): void
      
      forward(): void
Parameters

There are no parameters.

Returns

void

back()

Navigates back in the platform's history.
back(): void
      
      back(): void
Parameters

There are no parameters.

Returns

void

subscribe()

Subscribe to the platform's popState events.
subscribe(onNext: (value: PopStateEvent) => void, onThrow?: (exception: any) => void, onReturn?: () => void): SubscriptionLike
      
      subscribe(onNext: (value: PopStateEvent) => void, onThrow?: (exception: any) => void, onReturn?: () => void): SubscriptionLike
Parameters
onNext (value: PopStateEvent) => void
onThrow (exception: any) => void

Optional. Default is undefined.
onReturn () => void

Optional. Default is undefined.
Returns

SubscriptionLike: Subscribed events.

Usage notes

It's better to use the Router 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> ` }) export class PathLocationComponent { location: Location; constructor(location: Location) { this.location = location; } } 
      
      
  1. import {Location, LocationStrategy, PathLocationStrategy} from '@angular/common';
  2. import {Component} from '@angular/core';
  3.  
  4. @Component({
  5.   selector: 'path-location',
  6.   providers: [Location, {provide: LocationStrategy, useClass: PathLocationStrategy}],
  7.   template: `
  8.     <h1>PathLocationStrategy</h1>
  9.     Current URL is: <code>{{location.path()}}</code><br>
  10.     Normalize: <code>/foo/bar/</code> is: <code>{{location.normalize('foo/bar')}}</code><br>
  11.   `
  12. })
  13. export class PathLocationComponent {
  14.   location: Location;
  15.   constructor(location: Location) { this.location = location; }
  16. }