# Interface ParamDeclaration

Configuration for a single Parameter

In a [[StateDeclaration.params]], each `ParamDeclaration` defines how a single State Parameter should work.

#### Example:

    var mystate = {
      template: '<div ui-view/>',
      controller: function() {}
      url: '/mystate/:start?{count:int}',
      params: {
        start: { // <-- ParamDeclaration for `start`
          type: 'date',
          value: new Date(), // <-- Default value
          squash: true,
        },

        nonUrlParam: { // <-- ParamDeclaration for 'nonUrlParam'
         type: "int",
         array: true,
         value: []
        },

        count: 0, // <-- Default value for 'param1'
                  // (shorthand ParamDeclaration.value)
      }
    }

interface ParamDeclaration {
array?: boolean;
dynamic?: boolean;
inherit?: boolean;
isOptional?: boolean;
raw?: boolean;
replace?: Replace[];
squash?: string | boolean;
type?: string | ParamType;
value?: any;
}

- Defined in src/router/params/interface.ts:51

##### Index

### Properties

array?
dynamic?
inherit?
isOptional?
raw?
replace?
squash?
type?
value?

## Properties

### `Optional` array

array?: boolean

The parameter's `array` mode

Explicitly specifies the array mode of a URL parameter

- If `false`, the parameter value will be treated (encoded/decoded) as a single value
- If `true`, the parameter value will be treated (encoded/decoded) as an array of values.
- If `auto` (for query parameters only), if multiple values for a single parameter are present in the URL (e.g.: /foo?bar=1&bar=2&bar=3) then the values are mapped to an array (e.g.: `{ foo: [ '1', '2', '3' ] }`). However, if only one value is present (e.g.: /foo?bar=1) then the value is treated as single value (e.g.: { foo: '1' }).

If you specified a [[type]] for the parameter, the value will be treated as an array of the specified [[ParamType]].

#### Example:

    {
      name: 'foo',
      url: '/foo/{arrayParam:int}`,
      params: {
        arrayParam: { array: true }
      }
    }

    // After the transition, URL should be '/foo/1-2-3'
    $state.go("foo", { arrayParam: [ 1, 2, 3 ] });

#### Default

`false` for path parameters, such as `url: '/foo/:pathParam'`

#### Default

`auto` for query parameters, such as `url: '/foo?queryParam'`

#### Default

`true` if the parameter name ends in `[]`, such as `url: '/foo/{implicitArrayParam:int[]}'`

- Defined in src/router/params/interface.ts:163

### `Optional` dynamic

dynamic?: boolean

Dynamic flag

When `dynamic` is `true`, changes to the parameter value will not cause the state to be entered/exited. The resolves will not be re-fetched, nor will views be reloaded.

Normally, if a parameter value changes, the state which declared that the parameter will be reloaded (entered/exited). When a parameter is `dynamic`, a transition still occurs, but it does not cause the state to exit/enter.

This can be useful to build UI where the component updates itself when the param values change. A common scenario where this is useful is searching/paging/sorting.

Note: this value overrides the `dynamic` value on a custom parameter type ([[ParamTypeDefinition.dynamic]]).

Default: `false`

- Defined in src/router/params/interface.ts:267

### `Optional` inherit

inherit?: boolean

Enables/disables inheriting of this parameter's value

When a transition is run with [[TransitionOptions.inherit]] set to `true`, the current param values are inherited in the new transition. However, parameters values which have `inherit: false` set will not be inherited.

#### Example state :

    var fooState = {
      name: 'foo',
      url: '/:fooId?mode&refresh',
      params: {
        refresh: { inherit: false }
      }
    }

    // Set fooId to 123
    $state.go('fooState', { fooId: 1234, mode: 'list', refresh: true });

In the component: `mode: 'list' is inherited, but refresh: true is not inherited. // The param values are thus:` { fooId: 4567, mode: 'list' }`

    <ui-sref="foo({ fooId: 4567 })">4567</ui-sref>

See also [[TransitionOptions.inherit]] and [[ParamTypeDefinition.inherit]]

Default: `true`

- Defined in src/router/params/interface.ts:343

### `Optional` `Internal` isOptional

isOptional?: boolean

This is not part of the declaration; it is a calculated value depending on if a default value was specified or not.

- Defined in src/router/params/interface.ts:245

### `Optional` raw

raw?: boolean

Disables url-encoding of parameter values

When `true`, parameter values are not url-encoded. This is commonly used to allow "slug" urls, with a parameter value including non-semantic slashes.

#### Example:

    url: '/product/:slug',
    params: {
      slug: { type: 'string', raw: true }
    }

This allows a URL parameter of `{ slug: 'camping/tents/awesome_tent' }` to serialize to `/product/camping/tents/awesome_tent` instead of `/product/camping%2Ftents%2Fawesome_tent`.

Note: this value overrides the `raw` value on a custom parameter type ([[ParamTypeDefinition.raw]]).

### Decoding warning

The decoding behavior of raw parameters is not defined. For example, given a url template such as `/:raw1/:raw2` the url `/foo/bar/baz/qux/`, there is no way to determine which slashes belong to which params.

It's generally safe to use a raw parameter at the end of a path, like '/product/:slug'. However, beware of the characters you allow in your raw parameter values. Avoid unencoded characters that could disrupt normal URL parsing, such as `?` and `#`.

Default: `false`

- Defined in src/router/params/interface.ts:305

### `Optional` `Internal` replace

replace?: Replace[]

An array of [[Replace]] objects.

When creating a Transition, defines how to handle certain special values, such as `undefined`, `null`, or empty string `""`. If the transition is started, and the parameter value is equal to one of the "to" values, then the parameter value is replaced with the "from" value.

#### Example:

    replace: [
      { from: undefined, to: null },
      { from: "", to: null }
    ]

- Defined in src/router/params/interface.ts:237

### `Optional` squash

squash?: string | boolean

Squash mode: omit default parameter values in URL

Configures how a default parameter value is represented in the URL when the current parameter value is the same as the default value.

There are three squash settings:

- `false`: The parameter's default value is not squashed. It is encoded and included in the URL
- `true`: The parameter's default value is omitted from the URL. If the parameter is preceeded and followed by slashes in the state's url declaration, then one of those slashes are omitted. This can allow for cleaner looking URLs.
- `"&lt;arbitrary string&gt;"`: The parameter's default value is replaced with an arbitrary placeholder of your choice.

#### Example:

    {
      name: 'mystate',
      url: '/mystate/:myparam',
      params: {
        myparam: 'defaultParamValue'
        squash: true
      }
    }

    // URL will be `/mystate/`
    $state.go('mystate', { myparam: 'defaultParamValue' });

    // URL will be `/mystate/someOtherValue`
    $state.go('mystate', { myparam: 'someOtherValue' });

#### Example:

    {
      name: 'mystate2',
      url: '/mystate2/:myparam2',
      params: {
        myparam2: 'defaultParamValue'
        squash: "~"
      }
    }

    // URL will be `/mystate/~`
    $state.go('mystate', { myparam2: 'defaultParamValue' });

    // URL will be `/mystate/someOtherValue`
    $state.go('mystate', { myparam2: 'someOtherValue' });

Default: If squash is not set, it uses the configured default squash policy. (See [defaultSquashPolicy])

- Defined in src/router/params/interface.ts:218

### `Optional` type

type?: string | ParamType

The parameter's type

Specifies the [[ParamType]] of the parameter. Parameter types can be used to customize the encoding/decoding of parameter values.

Set this property to the name of parameter's type. The type may be either one of the built in types, or a custom type that has been registered with the [[UrlMatcherFactory]].

See [[ParamTypes]] for the list of built in types.

Default:

- Path parameters (`/:fooParam`): `path`
- Query parameters (`?queryParam`): `query`
- Non-url parameters (`param: { foo: null }`): `any`

- Defined in src/router/params/interface.ts:128

### `Optional` value

value?: any

The default value for this parameter.

Specifies the default value for this parameter. This implicitly sets this parameter as optional.

When UI-Router routes to a state and no value is specified for this parameter in the URL or transition, the default value will be used instead. If value is a function, it will be injected and invoked, and the return value used.

Note: `value: undefined` is treated as though no default value was specified, while `value: null` is treated as "the default value is null".

    // define default values for param1 and param2
    params: {
      param1: {
        value: "defaultValue"
      },
      param2: {
        value: "param2Default;
      }
    }

### Shorthand Declaration

If you only want to set the default value of the parameter, you may use a shorthand syntax. In the params map, instead mapping the param name to a full parameter configuration object, simply set map it to the default parameter value, e.g.:

    // Normal (non-shorthand) default value syntax
    params: {
      param1: {
        value: "defaultValue"
      },
      param2: {
        value: "param2Default"
      }
    }

    // Shorthand default value syntax
    params: {
      param1: "defaultValue",
      param2: "param2Default"
    }

This defines a default value for the parameter. If a parameter value is `undefined`, this default value will be used instead

Default: `undefined`

- Defined in src/router/params/interface.ts:107