directives | @uirouter/angularjs
Options
Menu

Module directives

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.

Index

Variables

uiSref: ng1_directive

ui-sref: A directive for linking to a state

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.

Linked State

The attribute value of the ui-sref is the name of the state to link to.

Example:

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.

Example:

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>

hrefs

If the linked state has a URL, the directive will automatically generate and update the href attribute (using the StateService.href method).

Example:

Assuming the users state has a url of /users/

<a ui-sref="users" href="/users/">Users</a>

Parameter Values

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.

Example:

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.

Transition Options

You can specify TransitionOptions to pass to StateService.go by using the ui-sref-opts attribute. Options are restricted to location, inherit, and reload.

Example:

<a ui-sref="home" ui-sref-opts="{ reload: true }">Home</a>

Other DOM Events

You can also customize which DOM events to respond to (instead of click) by providing an events array in the ui-sref-opts attribute.

Example:

<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.

Examples

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>

Notes

  • You can use ui-sref to change only the parameter values by omitting the state name and parentheses.

    Example:

    Sets the 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.

uiSrefActive: ng1_directive

ui-sref-active and ui-sref-active-eq: A directive that adds a CSS class when a ui-sref is active

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.

Linking to a ui-sref or ui-state

ui-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.

Matching

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.

Parameter values

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.

Example:

<li ng-repeat="user in users" ui-sref-active="active">
  <a ui-sref="user.details({ userId: user.id })"></a>
</li>

Examples

Given the following template:

Example:

<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>

Glob mode

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.

Example:

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

uiState: ng1_directive

ui-state: A fully dynamic directive for linking to a state

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.

Linked State

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.

Example:

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.

hrefs

If the linked state has a URL, the directive will automatically generate and update the href attribute (using the StateService.href method).

Parameter Values

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.

Example:

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>

Transition Options

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.

Example:

<a ui-state="returnto.state" ui-state-opts="{ reload: true }">Home</a>

Other DOM Events

You can also customize which DOM events to respond to (instead of click) by providing an events array in the ui-state-opts attribute.

Example:

<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.

Notes

  • You can use 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.

Example:

Sets the lang parameter to en and remains on the same state.

<a ui-state="" ui-state-params="{ 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. ```
uiView: ng1_directive

ui-view: A viewport directive which is filled in by a view from the active state.

ui-view: A viewport directive which is filled in by a view from the active state.

Attributes

  • 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.

Example:

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/>"
    }
  }
})

Examples for 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.

Example:

$stateProvider.state('home', {
  template: '<my-component user="$resolve.user"></my-component>',
  resolve: {
    user: function(UserService) { return UserService.fetchUser(); }
  }
});

Generated using TypeDoc