Banner animations

The Banner animation plugin integrates GSAP into the eWizard.js framework, providing timeline-based animations for banner components. Animations are data-driven: JSON configuration defines what effects are available, and the <animation> block in each banner component controls what plays and when.

When the banner template initialises, eWizard.js framework merges the standard animations with custom animations defined at the template level (common/resources/animations.json by default). Each animation definition is registered as a named GSAP effect so it can be called by name from a timeline.

Each banner template you're animating contains an <animation> block in the template that defines the animation state.

`<animation>` block

Place an <animation> block in a banner component's single-file component to declare the timeline for that banner. The block contains a single JSON object, where ID is required and its format is bannerId-timeline.

html

<animation>
{
  "timeline": {
    "id": "banner1-timeline",
    "defaults": { "ease": "ewizardjs.ease", "duration": 0.8 },
    "animations": [
      { "target": "#logo", "animation": "fadeIn", "position": 0 },
      { "target": "#title", "animation": "backInDown", "position": "+=0.2", "repeat": 0 },
      { "target": "#cta", "animation": "fadeInUp", "position": "+=0" }
    ]    
  }
}
</animation>

Timeline options

The timeline object inside the <animation> block accepts the following parameters to configure the timing and sequence behavior of the banner animation:

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier passed to `gsap.timeline({ id })`, where ID is required and its format is `bannerId-timeline`.
`defaults`	`object`	No	GSAP `defaults` vars applied to every animation in this timeline (e.g., `ease`, `duration`).
`animations`	`array`	Yes	Ordered list of animation entries.

Animation entries

Each entry in animations describes one tween added to the timeline.

Field	Type	Required	Description
`target`	`string`	Yes	CSS selector for the element(s) to animate.
`animation`	`string`	Yes	Name of a registered animation effect (e.g., `"fadeIn"`).
`position`	`string \| number`	Yes	Timeline position. (default = "+=0") - controls the insertion point in the timeline. For more details, see Position Syntax.
`vars`	`object`	No	Per-entry overrides for the animation's `vars`. The `vars` values have a higher priority over the timeline `defaults` and the animation definition and overrides them.

Variable merge order

Since animation variables can be declared at multiple levels within a template, eWizard.js resolves potential configuration conflicts by merging variables in the following order of precedence (from lowest to highest):

Animation definition defaults (vars from animations.json).
Timeline defaults.
Entry-level vars.

Position syntax

The position field follows the standard GSAP timeline position parameter syntax.

Value	Meaning
`0`	Absolute time at 0 seconds.
`"+=0.5"`	0.5 s after the end of the previous tween.
`"-=0.3"`	0.3 s before the end of the previous tween.
`"<"`	Start at the same time as the previous tween.
`"<0.2"`	0.2 s after the start of the previous tween.

Configuration files

The animation configuration file is a JSON configuration that defines animations available for use in banners.

Standard animations

The framework contains a set of built-in animations. These are available in every banner template without any additional configuration.

Custom animations (`animations.json`)

To add template-level animations, create a JSON file whose path is configured via path.common.animations in system settings (defaults to common/resources/animations.json).

json

{
  "animations": {
    "mySlideIn": {
      "title": "My Slide In",
      "group": { "name": "entrance", "title": "Entrance" },
      "type":  { "name": "slide",    "title": "Slide"    },
      "method": "from",
      "vars": {
        "duration": 0.6,
        "ease": "ewizardjs.ease",
        "xPercent": "-=120",
        "opacity": 0
      }
    }
  },
  "customEases": {
    "ease": {
      "data": "M0,0 C0.25,0.1 0.25,1 1,1"
    }
  }
}

Custom animations are merged on top of standard ones. If a custom animation key matches a standard key, the custom definition replaces the standard one entirely.

Animation definition schema

When defining custom animations in animations.json, use the following schema parameters to configure their metadata, easing, and properties for the editor UI:

Field	Type	Required	Description
`title`	`string`	Yes	Human-readable name displayed in eWizard Editor.
`enabled`	`boolean`	No	Set to `false` to disable the animation (default `true`).
`group`	`object`	Yes	Grouping metadata: `{ name, title }`. Values: `entrance`, `exit`, `emphasis`. Only these 3 animation groups are supported by eWizard Editor.
`type`	`object`	Yes	Type metadata: `{ name, title }`. E.g., `fade`, `slide`, `bounce`. `title` is a human-readable name displayed in eWizard Editor.
`method`	`string`	Yes	GSAP method: `to`, `from`, or `fromTo`.
`vars`	`object`	Yes	GSAP tween vars. May include special properties like `startAt` and `keyframes`, and others, as well as CSS properties you want to animate. Please note that for the fromTo GSAP method, `fromVars` is also required.
`vars.fromVars`	`object`	No	For the `fromTo` method only: the starting state object containing the initial (starting) property/value pairs only for the `fromTo` method. Don't add any special properties here like `duration`, `ease`,and so on – those go in the `vars` property.

`fromTo` example

The following example illustrates how to configure a custom crossFade animation using the fromTo method, detailing both the starting configuration (fromVars) and the target state variables:

json

{
  "crossFade": {
    "title": "Cross Fade",
    "group": { "name": "entrance", "title": "Entrance" },
    "type":  { "name": "fade",     "title": "Fade"     },
    "method": "fromTo",
    "vars": {
      "fromVars": { "opacity": 0 },
      "opacity": 1,
      "duration": 1,
      "ease": "ewizardjs.ease"
    }
  }
}

Custom eases

Define template-level easing curves in the customEases section of your custom animations.json. Each entry is registered via GSAP's CustomEase.

All custom ease names are automatically prefixed with ewizardjs. You define them without the prefix; you reference them with the prefix.

json

{
  "animations": {},
  "customEases": {
    "snappy": {
      "data": "M0,0 C0.4,0 0.2,1 1,1"
    }
  }
}

An example of a custom ease usage in your animation vars:

json

{ "ease": "ewizardjs.snappy" }

In addition to the standard GSAP eases, eWizard.js offers its own in-built eases:

Reference name	Description
`ewizardjs.ease`	Default smooth ease.
`ewizardjs.easeInBack`	Ease in with slight overshoot back.
`ewizardjs.easeInCubic`	Cubic ease in.
`ewizardjs.easeOutBack`	Ease out with slight overshoot.
`ewizardjs.easeOutQuart`	Quartic ease out.

Overriding standard animations

Define an entry in your custom animations.json with the same key as the standard animation. The custom definition replaces the standard one completely.

json

{
  "animations": {
    "fadeIn": {
      "title": "Fade in (custom)",
      "group": { "name": "entrance", "title": "Entrance" },
      "type":  { "name": "fade",     "title": "Fade"     },
      "method": "from",
      "vars": {
        "duration": 0.4,
        "ease": "ewizardjs.easeInBack",
        "opacity": 0
      }
    }
  }
}

Disabling standard animations

To remove a standard animation from the registry entirely, define it in the custom animations.json configuration file with "enabled": false:

json

{
  "animations": {
    "bounce": {
      "enabled": false
    }
  }
}

As a result, bounce will no longer be registered and will not be available for use in any banner animation.

Standard animation reference

The eWizard.js framework provides a set of pre-configured, standard animations. You can reference any of these animation keys directly within your template's <animation> block.

Entrance

Key	Title
`fadeIn`	Fade in
`fadeInDown`	Fade from top
`fadeInUp`	Fade from bottom
`fadeInLeft`	Fade from left
`fadeInRight`	Fade from right
`fadeInTopLeft`	Fade from top-left
`fadeInTopRight`	Fade from top-right
`fadeInBottomLeft`	Fade from bottom-left
`fadeInBottomRight`	Fade from bottom-right
`backInDown`	Fly in from top
`backInLeft`	Fly in from left
`backInRight`	Fly in from right
`backInUp`	Fly in from bottom
`bounceIn`	Bounce in
`bounceInDown`	Bounce from top
`bounceInLeft`	Bounce from left
`bounceInRight`	Bounce from right
`bounceInUp`	Bounce from bottom
`rotateIn`	Rotate in
`rotateInDownLeft`	Rotate from top-left
`rotateInDownRight`	Rotate from top-right
`rotateInUpLeft`	Rotate from bottom-left
`rotateInUpRight`	Rotate from bottom-right
`slideInDown`	Slide down
`slideInLeft`	Slide from left
`slideInRight`	Slide from right
`slideInUp`	Slide up
`zoomIn`	Zoom in
`zoomInDown`	Zoom from top
`zoomInLeft`	Zoom from left
`zoomInRight`	Zoom from right
`zoomInUp`	Zoom from bottom

Emphasis

Key	Title
`bounce`	Bounce
`heartBeat`	Heartbeat
`pulse`	Pulse
`rubberBand`	Rubber
`shakeX`	Shake X
`shakeY`	Shake Y
`swing`	Swing

Exit

Key	Title
`fadeOut`	Fade out
`fadeOutDown`	Fade to bottom
`fadeOutUp`	Fade to top
`fadeOutLeft`	Fade to left
`fadeOutRight`	Fade to right
`fadeOutTopLeft`	Fade to top-left
`fadeOutTopRight`	Fade to top-right
`fadeOutBottomLeft`	Fade to bottom-left
`fadeOutBottomRight`	Fade to bottom-right
`backOutDown`	Fly out to bottom
`backOutLeft`	Fly out to left
`backOutRight`	Fly out to right
`backOutUp`	Fly out to top
`bounceOut`	Bounce out
`bounceOutDown`	Bounce to bottom
`bounceOutLeft`	Bounce to left
`bounceOutRight`	Bounce to right
`bounceOutUp`	Bounce to top
`rotateOut`	Rotate out
`rotateOutDownLeft`	Rotate to bottom-left
`rotateOutDownRight`	Rotate to bottom-right
`rotateOutUpLeft`	Rotate to top-left
`rotateOutUpRight`	Rotate to top-right
`slideOutDown`	Slide down
`slideOutLeft`	Slide to left
`slideOutRight`	Slide to right
`slideOutUp`	Slide up
`zoomOut`	Zoom out
`zoomOutDown`	Zoom to bottom
`zoomOutLeft`	Zoom to left
`zoomOutRight`	Zoom to right
`zoomOutUp`	Zoom to top

Plugin API (`$animation`)

The eWizard.js framework exposes this.$animation in every Vue component instance with certain properties and methods.

Properties

Property	Type	Description
`gsap`	`gsap`	The global GSAP instance. You can use this to call any GSAP API directly.
`animationsList`	`AnimationsList`	All registered animations (standard + custom merged).
`standardAnimationsList`	`AnimationsConfig`	Standard animations only.
`customAnimationsList`	`AnimationsConfig`	Custom animations only.
`hasAnimations`	`boolean`	`true` if the current banner has at least one animation defined in its timeline.
`timeline`	`gsap.core.Timeline \| null`	The active GSAP timeline for the current banner, or `null` if none is built.

Methods

The $animation helper exposes utility methods to programmatically control timeline playback and execution states.

Timeline control

The following methods are available for you to pause, play, restart, or seek to a specific time within the active GSAP timeline:

$animation.play(at?, suppress?): gsap.core.Timeline | undefined

Plays the current timeline from its current position, or from at if provided. Proxies directly to gsap.core.Timeline.play().

$animation.pause(at?, suppress?): gsap.core.Timeline | undefined

Pauses the current timeline. Proxies to gsap.core.Timeline.pause().

$animation.restart(includeDelay?, suppress?): gsap.core.Timeline | undefined

Restarts the current timeline from the beginning. Proxies to gsap.core.Timeline.restart().

$animation.seek(time, suppress?): gsap.core.Timeline | undefined

Jumps to a specific time position in the timeline without affecting its playing state.

Banner animations ​

<animation> block ​

Timeline options ​

Animation entries ​

Variable merge order ​

Position syntax ​

Configuration files ​

Standard animations ​

Custom animations (animations.json) ​

Animation definition schema ​

fromTo example ​

Custom eases ​

Overriding standard animations ​

Disabling standard animations ​

Standard animation reference ​

Entrance ​

Emphasis ​

Exit ​

Plugin API ($animation) ​

Properties ​

Methods ​

Timeline control ​

`<animation>` block

Timeline options

Animation entries

Variable merge order

Position syntax

Configuration files

Standard animations

Custom animations (`animations.json`)

Animation definition schema

`fromTo` example

Custom eases

Overriding standard animations

Disabling standard animations

Standard animation reference

Entrance

Emphasis

Exit

Plugin API (`$animation`)

Properties

Methods

Timeline control