gsap-controller v1.0.19
GSAP Controller
A customizable controller for managing GSAP animations in the browser.
Installation
You can install the GSAP Controller package using npm:
npm install gsap-controller
Usage
Import the GSAPController class and create an instance with your desired configurations:
import GSAPController from "gsap-controller";
// Define your GSAP animations using `gsap.to()` or `gsap.timeline()`, and give them distinct IDs for better identification:
const squareTl = gsap.timeline({ paused: true });
squareTl
.to(".square", { x: 300 })
.to(".square", {
rotate: "360",
})
.to(".square", { scale: 1.5 }, "<");
squareTl.id = "Animation Square";
const circle = gsap.to(".circle", {
background: "blue",
x: 400,
duration: 10,
});
new GSAPController({
animations: [squareTl, circle], // pass array of tweens or timeline
// animations: squareTl, // pass a single tween or timeline
});
Configuration Options
- animations: A single tween timeline or and array of tweens and timelines. Required
- Draggable: A Draggable instance for making the controller draggable. Optional
- position: The position of the controller (default: 'bottom center').Optional
- theme: The theme for the controller (default: 'default').Optional
- backgroundColor: Background color for the controller (string).Optional
- buttonColor: Button color for the controller (string).Optional
- textColor: Text color for the controller (string).Optional
- width: Width of container, default 500px,(eg:"100px" or "100%"). Optional
- disable: Default false.(boolean) Optional
- activeAnimation: Animation id. Set default animation. Optional
- parentSelector: Class name or Id. The controller will be appended to that element. Optional
- onStart: Callback function that fires when the controller is instantiated. This function receives the active animation timeline as a parameter.
- onSelectAnimationChange: Callback function that fires every time a new animation is selected. This function also receives the active animation timeline as a parameter.
new GSAPController({
animations: [squareTl, circle],
Draggable,
theme: "cool",
position: "top right",
width: "700px",
buttonColor: "red",
backgroundColor: "orange",
textColor: "blue",
activeAnimation: "Square Animation", // Set default the animation
parentSelector: "#parent", // Append the controller to a specific DOM ELEMENT
onStart: (animation) => {}, // callback that fire when instantiated,
onSelectAnimationChange: (animation) => {}, // callback that fire every time a new animation is selected
});
Select Active Animation
You can easily choose and control different animations using the select dropdown provided by the GSAP Controller. This feature allows you to manage multiple animations and control their playback seamlessly.
- Define your GSAP animations using
gsap.to()
orgsap.timeline()
, and give them distinct IDs for better identification:
const squareTl = gsap.timeline({ paused: true });
squareTl
.to(".square", { x: 300 })
.to(".square", {
rotate: "360",
})
.to(".square", { scale: 1.5 }, "<");
squareTl.id = "Square Animation"; // Customize the animation ID
const circle = gsap.to(".circle", {
background: "blue",
x: 400,
duration: 10,
});
circle.id = "Circle Animation"; // Customize the animation ID
Enabling the Draggable Feature
The GSAP Controller package offers the ability to make the controller itself draggable using the GSAP Draggable plugin. This allows you to easily move the controller around the screen as needed. To enable this feature, follow these steps:
- First, make sure you have the necessary modules imported at the beginning of your script:
import GSAPController from "gsap-controller";
import Draggable from "gsap/Draggable.js";
import gsap from "gsap";
gsap.registerPlugin(Draggable);
const squareTl = gsap.timeline({ paused: true });
squareTl
.to(".square", { x: 300 })
.to(".square", {
rotate: "360",
})
.to(".square", { scale: 1.5 }, "<");
const controller = new GSAPController({
animations: squareTl,
Draggable, // Enable the draggable feature
});
- Drag the container around grabbing it from the top right corner.
Positions
If you don't want to use the draggable feature you can still position the container using the following values.
- 'top left'
- 'top center'
- 'top right'
- 'center left'
- 'center center'
- 'center right'
- 'bottom left'
- 'bottom center'
- 'bottom right'
Appending Controller to Specified Parent Element
The GSAP Controller supports appending the controller to a specified parent element using the parentSelector
property. This feature provides more flexibility in where the controller is placed within the DOM.
To use this feature, follow these guidelines:
Include the
parentSelector
property when creating a new instance of the GSAP Controller. You can pass a class name, or ID as the value.If
parentSelector
corresponds to a valid DOM element, the controller will be appended to that parent element. If the element is not found or theparentSelector
is not provided, the controller will be appended to thebody
element by default.
Themes
The package provides several themes you can choose from:
- default: A default light theme.
- elegant: An elegant dark theme.
- cool: A cool blue theme.
- warm: A warm orange theme.
- dark: A dark theme suitable for low-light environments.
License
This package is released under the MIT License.