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.
Home
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 class.
<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>
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-sref="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>
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.