{ "id": "api/animations/trigger", "title": "trigger", "contents": "\n\n
\n
\n
\n \n API > @angular/animations\n
\n
\n mode_edit\n code\n
\n
\n \n
\n

triggerlink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

Creates a named animation trigger, containing a list of state()\nand transition() entries to be evaluated when the expression\nbound to the trigger changes.

\n\n \n
\n \n \n \n\n
\n \n\n trigger(name: string, definitions: AnimationMetadata[]): AnimationTriggerMetadata\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n name\n string\n

An identifying string.

\n\n
\n \n definitions\n AnimationMetadata[]\n

An animation definition object, containing an array of state()\nand transition() declarations.

\n\n
\n\n \n
Returns
\n

AnimationTriggerMetadata: An object that encapsulates the trigger data.

\n \n \n\n\n \n\n \n
\n\n\n \n\n \n\n\n\n \n
\n

Usage noteslink

\n

Define an animation trigger in the animations section of @Component metadata.\nIn the template, reference the trigger by name and bind it to a trigger expression that\nevaluates to a defined animation state, using the following format:

\n

[@triggerName]=\"expression\"

\n

Animation trigger bindings convert all values to strings, and then match the\nprevious and current values against any linked transitions.\nBooleans can be specified as 1 or true and 0 or false.

\n

Usage Examplelink

\n

The following example creates an animation trigger reference based on the provided\nname value.\nThe provided animation value is expected to be an array consisting of state and\ntransition declarations.

\n\n@Component({\n selector: \"my-component\",\n templateUrl: \"my-component-tpl.html\",\n animations: [\n trigger(\"myAnimationTrigger\", [\n state(...),\n state(...),\n transition(...),\n transition(...)\n ])\n ]\n})\nclass MyComponent {\n myStatusExp = \"something\";\n}\n\n

The template associated with this component makes use of the defined trigger\nby binding to an element within its template code.

\n\n<!-- somewhere inside of my-component-tpl.html -->\n<div [@myAnimationTrigger]=\"myStatusExp\">...</div>\n\n

Using an inline functionlink

\n

The transition animation method also supports reading an inline function which can decide\nif its associated animation should be run.

\n\n// this method is run each time the `myAnimationTrigger` trigger value changes.\nfunction myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key:\n string]: any}): boolean {\n // notice that `element` and `params` are also available here\n return toState == 'yes-please-animate';\n}\n\n@Component({\n selector: 'my-component',\n templateUrl: 'my-component-tpl.html',\n animations: [\n trigger('myAnimationTrigger', [\n transition(myInlineMatcherFn, [\n // the animation sequence code\n ]),\n ])\n ]\n})\nclass MyComponent {\n myStatusExp = \"yes-please-animate\";\n}\n\n

Disabling Animationslink

\n

When true, the special animation control binding @.disabled binding prevents\nall animations from rendering.\nPlace the @.disabled binding on an element to disable\nanimations on the element itself, as well as any inner animation triggers\nwithin the element.

\n

The following example shows how to use this feature:

\n\n@Component({\n selector: 'my-component',\n template: `\n <div [@.disabled]=\"isDisabled\">\n <div [@childAnimation]=\"exp\"></div>\n </div>\n `,\n animations: [\n trigger(\"childAnimation\", [\n // ...\n ])\n ]\n})\nclass MyComponent {\n isDisabled = true;\n exp = '...';\n}\n\n

When @.disabled is true, it prevents the @childAnimation trigger from animating,\nalong with any inner animations.

\n

Disable animations application-widelink

\n

When an area of the template is set to have animations disabled,\nall inner components have their animations disabled as well.\nThis means that you can disable all animations for an app\nby placing a host binding set on @.disabled on the topmost Angular component.

\n\nimport {Component, HostBinding} from '@angular/core';\n\n@Component({\n selector: 'app-component',\n templateUrl: 'app.component.html',\n})\nclass AppComponent {\n @HostBinding('@.disabled')\n public animationsDisabled = true;\n}\n\n

Overriding disablement of inner animationslink

\n

Despite inner animations being disabled, a parent animation can query()\nfor inner elements located in disabled areas of the template and still animate\nthem if needed. This is also the case for when a sub animation is\nqueried by a parent and then later animated using animateChild().

\n

Detecting when an animation is disabledlink

\n

If a region of the DOM (or the entire application) has its animations disabled, the animation\ntrigger callbacks still fire, but for zero seconds. When the callback fires, it provides\nan instance of an AnimationEvent. If animations are disabled,\nthe .disabled flag on the event is true.

\n\n
\n\n\n\n
\n
\n\n\n" }