1 | # UI-Router Core [![Build Status](https://github.com/ui-router/core/workflows/CI:%20UIRouter%20Core/badge.svg)](https://github.com/ui-router/core/actions?query=workflow%3A%22CI:%20UIRouter%20Core%22)
|
2 |
|
3 | UI-Router core provides client-side [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application)
|
4 | routing for JavaScript.
|
5 | This core is framework agnostic.
|
6 | It is used to build
|
7 | [UI-Router for Angular 1](//ui-router.github.io/ng1),
|
8 | [UI-Router for Angular 2](//ui-router.github.io/ng2), and
|
9 | [UI-Router React](//ui-router.github.io/react).
|
10 |
|
11 | ## SPA Routing
|
12 |
|
13 | Routing frameworks for SPAs update the browser's URL as the user navigates through the app. Conversely, this allows
|
14 | changes to the browser's URL to drive navigation through the app, thus allowing the user to create a bookmark to a
|
15 | location deep within the SPA.
|
16 |
|
17 | UI-Router applications are modeled as a hierarchical tree of states. UI-Router provides a
|
18 | [_state machine_](https://en.wikipedia.org/wiki/Finite-state_machine) to manage the transitions between those
|
19 | application states in a transaction-like manner.
|
20 |
|
21 | ## Features
|
22 |
|
23 | UI-Router Core provides the following features:
|
24 |
|
25 | - State-machine based routing
|
26 | - Hierarchical states
|
27 | - Enter/Exit hooks
|
28 | - Name based hierarchical state addressing
|
29 | - Absolute, e.g., `admin.users`
|
30 | - Relative, e.g., `.users`
|
31 | - Flexible Views
|
32 | - Nested Views
|
33 | - Multiple Named Views
|
34 | - Flexible URLs and parameters
|
35 | - Path, Query, and non-URL parameters
|
36 | - Typed parameters
|
37 | - Built in: `int`, `string`, `date`, `json`
|
38 | - Custom: define your own encoding/decoding
|
39 | - Optional or required parameters
|
40 | - Default parameter values (optionally squashed from URL)
|
41 | - Transaction-like state transitions
|
42 | - Transition Lifecycle Hooks
|
43 | - First class async support
|
44 |
|
45 | ## Get Started
|
46 |
|
47 | Get started using one of the existing UI-Router projects:
|
48 |
|
49 | - [UI-Router for Angular 1](https://ui-router.github.io/ng1)
|
50 | - [UI-Router for Angular 2](https://ui-router.github.io/ng2)
|
51 | - [UI-Router for React](https://ui-router.github.io/react)
|
52 |
|
53 | ## Build your own
|
54 |
|
55 | UI-Router core can be used implement a router for any web-based component framework.
|
56 | There are four basic things to build for a specific component framework:
|
57 |
|
58 | ### UIView
|
59 |
|
60 | A UIView is a component which acts as a viewport for another component, defined by a state.
|
61 | When the state is activated, the UIView should render the state's component.
|
62 |
|
63 | ### UISref (optional, but useful)
|
64 |
|
65 | A `UISref` is a link (absolute, or relative) which activates a specific state and/or parameters.
|
66 | When the `UISref` is clicked, it should initiate a transition to the linked state.
|
67 |
|
68 | ### UISrefActive (optional)
|
69 |
|
70 | When combined with a `UISref`, a `UISrefActive` toggles a CSS class on/off when its `UISref` is active/inactive.
|
71 |
|
72 | ### Integrate with your framework's bootstrap mechanism (optional)
|
73 |
|
74 | Implement framework specific bootstrap requirements, if any.
|
75 | For example, UI-Router for Angular 1 and Angular 2 integrates with the ng1/ng2 Dependency Injection lifecycles.
|
76 | On the other hand, UI-Router for React uses a simple JavaScript based bootstrap, i.e., `new UIRouterReact().start();`.
|
77 |
|
78 | ### Minimal Example
|
79 |
|
80 | This example doesn't have UIView, UISref, or anything like that.
|
81 | It bootstrap the router and naively manipulates the DOM when states are activated.
|
82 |
|
83 | https://stackblitz.com/edit/ui-router-plain-javascript?file=index.js
|
84 |
|
85 | Note: do not model your own router off this example, it is meant to show only the bare minimum.
|
86 |
|
87 | ## Getting help
|
88 |
|
89 | [Create an issue](https://github.com/ui-router/core/issues) or contact us on [Gitter](https://gitter.im/angular-ui/ui-router).
|