Skip to content
This repository has been archived by the owner on Nov 28, 2023. It is now read-only.

Latest commit

 

History

History
272 lines (189 loc) · 9.46 KB

Glossary.md

File metadata and controls

272 lines (189 loc) · 9.46 KB
Raw

Glossary

This is a glossary of common terms used in the React Router codebase and documentation listed in alphabetical order, along with their type signatures.

Action

type Action = 'PUSH' | 'REPLACE' | 'POP';

An action describes the type of change to a URL. Possible values are:

  • PUSH – indicates a new item was added to the history
  • REPLACE – indicates the current item in history was altered
  • POP – indicates there is a new current item, i.e. the "current pointer" changed

Component

type Component = ReactClass | string;

A component is a React component class or a string (e.g. "div"). Basically, it's anything that can be used as the first argument to React.createElement.

EnterHook

type EnterHook = (nextState: RouterState, replace: RedirectFunction, callback?: Function) => any;

An enter hook is a user-defined function that is called when a route is about to be rendered. It receives the next router state as its first argument. The replace function may be used to trigger a transition to a different URL.

If an enter hook needs to execute asynchronously, it may list a 3rd callback argument that it must call in order to cause the transition to proceed.

Caution: Using the callback in an enter hook causes the transition to wait until it is called. This can lead to a non-responsive UI if you don't call it very quickly.

Hash

type Hash = string;

A hash is a string that represents the hash portion of the URL. It is synonymous with window.location.hash in web browsers.

LeaveHook

type LeaveHook = (prevState: RouterState) => any;

A leave hook is a user-defined function that is called when a route is about to be unmounted. It receives the previous router state as its first argument.

Location

type Location = {
  pathname: Pathname;
  search: QueryString;
  query: Query;
  state: LocationState;
  action: Action;
  key: LocationKey;
};

A location answers two important (philosophical) questions:

  • Where am I?
  • How did I get here?

New locations are typically created each time the URL changes. You can read more about locations in the history docs.

LocationDescriptor

type LocationDescriptorObject = {
  pathname: Pathname;
  search: Search;
  query: Query;
  state: LocationState;
};

type LocationDescriptor = LocationDescriptorObject | Path;

A location descriptor is the pushable analogue of a location. Locations tell you where you are; you create location descriptors to say where to go.

You can read more about location descriptors in the history docs.

LocationKey

type LocationKey = string;

A location key is a string that is unique to a particular location. It is the one piece of data that most accurately answers the question "Where am I?".

LocationState

type LocationState = ?Object;

A location state is an arbitrary object of data associated with a particular location. This is basically a way to tie extra state to a location that is not contained in the URL.

This type gets its name from the first argument to HTML5's pushState and replaceState methods.

Params

type Params = Object;

The word params refers to an object of key/value pairs that were parsed out of the original URL's pathname. The values of this object are typically strings, unless there is more than one param with the same name in which case the value is an array.

Path

type Path = Pathname + QueryString + Hash;

A path represents a URL path.

Pathname

type Pathname = string;

A pathname is the portion of a URL that describes a hierarchical path, including the preceding /. For example, in http://example.com/the/path?the=query, /the/path is the pathname. It is synonymous with window.location.pathname in web browsers.

Query

type Query = Object;

A query is the parsed version of a query string.

QueryString

type QueryString = string;

A query string is the portion of the URL that follows the pathname, including any preceding ?. For example, in http://example.com/the/path?the=query, ?the=query is the query string. It is synonymous with window.location.search in web browsers.

RedirectFunction

type RedirectFunction = (state: ?LocationState, pathname: Pathname | Path, query: ?Query) => void;

A redirect function is used in onEnter hooks to trigger a transition to a new URL.

Route

type Route = {
  component: RouteComponent;
  path: ?RoutePattern;
  onEnter: ?EnterHook;
  onLeave: ?LeaveHook;
};

A route specifies a component that is part of the user interface (UI). Routes should be nested in a tree-like structure that follows the hierarchy of your components.

It may help to think of a route as an "entry point" into your UI. You don't need a route for every component in your component hierarchy, only for those places where your UI differs based on the URL.

RouteComponent

type RouteComponent = Component;

The term route component refers to a component that is directly rendered by a route (i.e. the <Route component>). The router creates elements from route components and provides them as this.props.children to route components further up the hierarchy. In addition to children, route components receive the following props:

  • router – The router instance
  • location – The current location
  • params – The current params
  • route – The route that declared this component
  • routeParams – A subset of the params that were specified in the route's path

Route components should generally be component classes rather than strings. This will avoid potential issues with passing the injected props above to DOM components.

RouteConfig

type RouteConfig = Array<Route>;

A route config is an array of routes that specifies the order in which routes should be tried when the router attempts to match a URL.

RouteHook

type RouteHook = (nextLocation?: Location) => any;

A route hook is a function that is used to prevent the user from leaving a route. On normal transitions, it receives the next location as an argument and must either return false to cancel the transition or return a prompt message to show the user. When invoked during the beforeunload event in web browsers, it does not receive any arguments and must return a prompt message to cancel the transition.

RoutePattern

type RoutePattern = string;

A route pattern (or "path") is a string that describes a portion of a URL. Patterns are compiled into functions that are used to try and match a URL. Patterns may use the following special characters:

  • :paramName – matches a URL segment up to the next /, ?, or #. The matched string is called a param
  • () – Wraps a portion of the URL that is optional
  • * – Matches all characters (non-greedy) up to the next character in the pattern, or to the end of the URL if there is none, and creates a splat param
  • ** - Matches all characters (greedy) until the next /, ?, or # and creates a splat param

Route patterns are relative to the pattern of the parent route unless they begin with a /, in which case they begin matching at the beginning of the URL.

Router

type Router = {
  push(location: LocationDescriptor) => void;
  replace(location: LocationDescriptor) => void;
  go(n: number) => void;
  goBack() => void;
  goForward() => void;
  setRouteLeaveHook(route: Route, hook: RouteHook) => Function;
  isActive(location: LocationDescriptor, indexOnly: boolean) => void;
};

A router object allows for procedural manipulation of the routing state.

RouterState

type RouterState = {
  location: Location;
  routes: Array<Route>;
  params: Params;
  components: Array<Component>;
};

A router state represents the current state of a router. It contains:

  • the current location,
  • an array of routes that match that location,
  • an object of params that were parsed out of the URL, and
  • an array of components that will be rendered to the page in hierarchical order.