ui-sref: A directive for linking to a state
A directive which links to a state (and optionally, parameters). When clicked, this directive activates the linked state with the supplied parameter values.
The attribute value of the ui-sref is the name of the state to link to.
This will activate the home state when the link is clicked.
<a ui-sref="home">Home</a>
You can also use relative state paths within ui-sref, just like a relative path passed to $state.go() (StateService.go).
You just need to be aware that the path is relative to the state that created the link.
This allows a state to create a relative ui-sref which always targets the same destination.
Both these links are relative to the parent state, even when a child state is currently active.
<a ui-sref=".child1">child 1 state</a>
<a ui-sref=".child2">child 2 state</a>
This link activates the parent state.
<a ui-sref="^">Return</a>
If the linked state has a URL, the directive will automatically generate and
update the href attribute (using the StateService.href method).
Assuming the users state has a url of /users/
<a ui-sref="users" href="/users/">Users</a>
In addition to the state name, a ui-sref can include parameter values which are applied when activating the state.
Param values can be provided in the ui-sref value after the state name, enclosed by parentheses.
The content inside the parentheses is an expression, evaluated to the parameter values.
This example renders a list of links to users.
The state's userId parameter value comes from each user's user.id property.
<li ng-repeat="user in users">
<a ui-sref="users.detail({ userId: user.id })"></a>
</li>
Note:
The parameter values expression is $watched for updates.
You can specify TransitionOptions to pass to StateService.go by using the ui-sref-opts attribute.
Options are restricted to location, inherit, and reload.
<a ui-sref="home" ui-sref-opts="{ reload: true }">Home</a>
You can also customize which DOM events to respond to (instead of click) by
providing an events array in the ui-sref-opts attribute.
<input type="text" ui-sref="contacts" ui-sref-opts="{ events: ['change', 'blur'] }">
This directive can be used in conjunction with uiSrefActive to highlight the active link.
If you have the following template:
<a ui-sref="home">Home</a>
<a ui-sref="about">About</a>
<a ui-sref="{page: 2}">Next page</a>
<ul>
<li ng-repeat="contact in contacts">
<a ui-sref="contacts.detail({ id: contact.id })"></a>
</li>
</ul>
Then (assuming the current state is contacts) the rendered html including hrefs would be:
<a href="#/home" ui-sref="home">Home</a>
<a href="#/about" ui-sref="about">About</a>
<a href="#/contacts?page=2" ui-sref="{page: 2}">Next page</a>
<ul>
<li ng-repeat="contact in contacts">
<a href="#/contacts/1" ui-sref="contacts.detail({ id: contact.id })">Joe</a>
</li>
<li ng-repeat="contact in contacts">
<a href="#/contacts/2" ui-sref="contacts.detail({ id: contact.id })">Alice</a>
</li>
<li ng-repeat="contact in contacts">
<a href="#/contacts/3" ui-sref="contacts.detail({ id: contact.id })">Bob</a>
</li>
</ul>
<a href="#/home" ui-sref="home" ui-sref-opts="{reload: true}">Home</a>
ui-sref to change only the parameter values by omitting the state name and parentheses.lang parameter to en and remains on the same state.<a ui-sref="{ lang: 'en' }">English</a>
A middle-click, right-click, or ctrl-click is handled (natively) by the browser to open the href in a new window, for example.
Unlike the parameter values expression, the state name is not $watched (for performance reasons).
If you need to dynamically update the state being linked to, use the fully dynamic uiState directive.
ui-sref-active and ui-sref-active-eq: A directive that adds a CSS class when a ui-sref is active
A directive working alongside uiSref and uiState to add classes to an element when the related directive's state is active (and remove them when it is inactive).
The primary use-case is to highlight the active link in navigation menus, distinguishing it from the inactive menu items.
ui-sref or ui-stateui-sref-active can live on the same element as ui-sref/ui-state, or it can be on a parent element.
If a ui-sref-active is a parent to more than one ui-sref/ui-state, it will apply the CSS class when any of the links are active.
The ui-sref-active directive applies the CSS class when the ui-sref/ui-state's target state or any child state is active.
This is a "fuzzy match" which uses StateService.includes.
The ui-sref-active-eq directive applies the CSS class when the ui-sref/ui-state's target state is directly active (not when child states are active).
This is an "exact match" which uses StateService.is.
If the ui-sref/ui-state includes parameter values, the current parameter values must match the link's values for the link to be highlighted.
This allows a list of links to the same state with different parameters to be rendered, and the correct one highlighted.
<li ng-repeat="user in users" ui-sref-active="active">
<a ui-sref="user.details({ userId: user.id })"></a>
</li>
Given the following template:
<ul>
<li ui-sref-active="active" class="item">
<a href ui-sref="app.user({user: 'bilbobaggins'})">@bilbobaggins</a>
</li>
</ul>
When the app state is app.user (or any child state),
and contains the state parameter "user" with value "bilbobaggins",
the resulting HTML will appear as (note the 'active' class):
<ul>
<li ui-sref-active="active" class="item active">
<a ui-sref="app.user({user: 'bilbobaggins'})" href="/users/bilbobaggins">@bilbobaggins</a>
</li>
</ul>
It is possible to pass ui-sref-active an expression that evaluates to an object.
The objects keys represent active class names and values represent the respective state names/globs.
ui-sref-active will match if the current active state includes any of
the specified state names/globs, even the abstract ones.
Given the following template, with "admin" being an abstract state:
<div ui-sref-active="{'active': 'admin.**'}">
<a ui-sref-active="active" ui-sref="admin.roles">Roles</a>
</div>
When the current state is "admin.roles" the "active" class will be applied to both the
ui-state: A fully dynamic directive for linking to a state
A directive which links to a state (and optionally, parameters). When clicked, this directive activates the linked state with the supplied parameter values.
This directive is very similar to uiSref, but it $observes and $watches/evaluates all its inputs.
A directive which links to a state (and optionally, parameters). When clicked, this directive activates the linked state with the supplied parameter values.
The attribute value of ui-state is an expression which is $watched and evaluated as the state to link to.
This is in contrast with ui-sref, which takes a state name as a string literal.
Create a list of links.
<li ng-repeat="link in navlinks">
<a ui-state="link.state"></a>
</li>
If the expression evaluates to a relative path, it is processed like uiSref.
You just need to be aware that the path is relative to the state that created the link.
This allows a state to create relative ui-state which always targets the same destination.
If the linked state has a URL, the directive will automatically generate and
update the href attribute (using the StateService.href method).
In addition to the state name expression, a ui-state can include parameter values which are applied when activating the state.
Param values should be provided using the ui-state-params attribute.
The ui-state-params attribute value is $watched and evaluated as an expression.
This example renders a list of links with param values.
The state's userId parameter value comes from each user's user.id property.
<li ng-repeat="link in navlinks">
<a ui-state="link.state" ui-state-params="link.params"></a>
</li>
You can specify TransitionOptions to pass to StateService.go by using the ui-state-opts attribute.
Options are restricted to location, inherit, and reload.
The value of the ui-state-opts is $watched and evaluated as an expression.
<a ui-state="returnto.state" ui-state-opts="{ reload: true }">Home</a>
You can also customize which DOM events to respond to (instead of click) by
providing an events array in the ui-state-opts attribute.
<input type="text" ui-state="contacts" ui-state-opts="{ events: ['change', 'blur'] }">
This directive can be used in conjunction with uiSrefActive to highlight the active link.
ui-params to change only the parameter values by omitting the state name and supplying only ui-state-params.
However, it might be simpler to use uiSref parameter-only links.Sets the lang parameter to en and remains on the same state.
<a ui-state="" ui-state-params="{ lang: 'en' }">English</a>
ui-view: A viewport directive which is filled in by a view from the active state.
name: (Optional) A view name.
The name should be unique amongst the other views in the same state.
You can have views of the same name that live in different states.
The ui-view can be targeted in a View using the name (Ng1StateDeclaration.views).
autoscroll: an expression. When it evaluates to true, the ui-view will be scrolled into view when it is activated.
Uses $uiViewScroll to do the scrolling.
onload: Expression to evaluate whenever the view updates.
A view can be unnamed or named.
<!-- Unnamed -->
<div ui-view></div>
<!-- Named -->
<div ui-view="viewName"></div>
<!-- Named (different style) -->
<ui-view name="viewName"></ui-view>
You can only have one unnamed view within any template (or root html). If you are only using a single view and it is unnamed then you can populate it like so:
<div ui-view></div>
$stateProvider.state("home", {
template: "<h1>HELLO!</h1>"
})
The above is a convenient shortcut equivalent to specifying your view explicitly with the Ng1StateDeclaration.views config property, by name, in this case an empty name:
$stateProvider.state("home", {
views: {
"": {
template: "<h1>HELLO!</h1>"
}
}
})
But typically you'll only use the views property if you name your view or have more than one view in the same template. There's not really a compelling reason to name a view if its the only one, but you could if you wanted, like so:
<div ui-view="main"></div>
$stateProvider.state("home", {
views: {
"main": {
template: "<h1>HELLO!</h1>"
}
}
})
Really though, you'll use views to set up multiple views:
<div ui-view></div>
<div ui-view="chart"></div>
<div ui-view="data"></div>
$stateProvider.state("home", {
views: {
"": {
template: "<h1>HELLO!</h1>"
},
"chart": {
template: "<chart_thing/>"
},
"data": {
template: "<data_thing/>"
}
}
})
autoscroll:<!-- If autoscroll present with no expression,
then scroll ui-view into view -->
<ui-view autoscroll/>
<!-- If autoscroll present with valid expression,
then scroll ui-view into view if expression evaluates to true -->
<ui-view autoscroll='true'/>
<ui-view autoscroll='false'/>
<ui-view autoscroll='scopeVariable'/>
Resolve data:
The resolved data from the state's resolve block is placed on the scope as $resolve (this
can be customized using Ng1ViewDeclaration.resolveAs). This can be then accessed from the template.
Note that when controllerAs is being used, $resolve is set on the controller instance after the
controller is instantiated. The $onInit() hook can be used to perform initialization code which
depends on $resolve data.
$stateProvider.state('home', {
template: '<my-component user="$resolve.user"></my-component>',
resolve: {
user: function(UserService) { return UserService.fetchUser(); }
}
});
Generated using TypeDoc
Angular 1 Directives
These are the directives included in UI-Router for Angular 1. These directives are used in templates to create viewports and link/navigate to states.