@adoratorio/apollo

Apollo

Create custom cursors with integrated animated props.

Installation

# Install package
npm install @adoratorio/apollo

Usage

Since this package has a pkg.module field, it’s highly recommended to import it as an ES6 module with some bundlers like webpack or rollup:

import Apollo from '@adoratorio/apollo';
const apollo = new Apollo({ });

If you are not using any bundlers, you can just load the UMD bundle:

<script src="/apollo/umd/index.js"></script>
<script>var apollo = window.Apollo({ });</script>

Available options

Medusa accept in the constructor and option object with the following possible props.

parameter	type	default	description
cursor	HTMLElement	'.apollo__cursor'	The HTML element reiceving the transforms to follow the mouse
props	Array<PropertyDescriptor>	[]	An array of Propery Descriptors to define wich props will be animated, a timeline will be created for each prop
easing	Easing	{ mode: Apollo.EASING.CUBIC, duration: 1000 }	An easing object used to describe the cursor element aniamtion
target	Array<TargetDescriptor>	[]	An array of Targets to describe witch elements will trigger an event when the mouse pass hover or out it
hiddenUntilFirstInteraction	boolean	false	If you want to keep the cursor element invisibile until the first valid user interaction is performed
initialPosition	Vec2	{ x: 0, y: 0 }	A Two components (x, y) vector to determinate the strarting position of the cursor element
detectTouch	boolean	true	If the touch events counts as valid interaction to evaluate a new cursor position
emitGlobal	boolean	true	If a global event is fired on window on items over or out
aion	Aion	new Aion()	An Aion instance to be used as engine, if not submitted one will be created for you
renderByPixel	boolean	false	If values rounding is used before applying styles

APIs

Targets are the interaction core, having callback and event on hover and leave of the element, you can define targets passing target descriptors to the constructor or using the dedicated method

apolloInstance.addTarget(targets Array<TargetDescriptor>)

Anytime an element in target is hovered or leaved a global event is emitted (if the emitGlobal option is set to true). Emitted events are

name	when
apollo-mouse-enter	When the mouse pointer enter a target
apollo-cursor-enter	When the cursor element enter a target
apollo-mouse-leave	When the mouse pointer leave a target
apollo-cursor-leave	When the cursor element enter a target

Having TargetDescriptor defined as follow

parameter	type	descriptor
id	string	The id of the target, used to identify the target
elements	Array<HTMLElement>	The HTMLElements array used to detect hover and leave
offset	{ x: number, y: number }	The offset that will trigger hover and leave on elements
callback	Function	Callback function for hover and leave
checkVisibility	Boolean	If you need to test the element visibility before triggering hover

You can animate some css, attributes or js values of the DOM cursor element, or any other DOM element actually, by passing in a property descriptor in the props array parameter in constructor or adding a prop with the dedicated method.

apolloInstance.addProperties(props : Array<PropertyDescriptor>)

Then when you need to update the value and make apollo to ease from the actual value to the newly setted one simply get the property and change its value like so

apolloInstance.getProperty(id : string).value = value : any;

Having the PropertyDescriptor defined ad follow

parameter	type	descriptor
id	string	The id that will be used to identify the property when accessing it
key	string	The key that will be used when rendering the animation, for example translateX
type	string	Determins how the property will be used when rendering can be Aplllo.PROPERTY_TYPE.TYPELESS or Apollo.PROPERTY_TYPE.STYLE or Apollo.PROPERTY_TYPE.TRANSFORM or Apollo.PROPERTY_TYPE.ATTRIBUTE
target	Element	The DOM element used as target for rendering, not needed if prop is typeless
suffix	string	The suffix string used to render css props or transform will be applied in the form of ${value}${suffix}
easing	{ mode: Function, duration: number }	The easing descriptor used to ease between values
initial	number	The starting value for the property
precision	number	Number of digits used to round the final rendered value

Each property exposes two additional methods: play and pause. Usable as follow

apolloInstance.getProperty('prop_id').pause();
apolloInstance.getProperty('prop_id').play(resumeValue? : number);

Watch out: if the current target of the prop is the cursor element itself and you are animating the translateX or translateY transform you need to call apolloInstance.stopMouseTracking() and later when you need to start the mouse following again apolloInstance.startMouseTracking().

Anyway this is not an actual animation engine, is used just to update some props around the cursor in a specific way avoiding the necessity to build a complete animation system. If you need more than this a complex animation system is required maybe with some animation frameworks.