Gilded is a JS animation and styling library to add some shine to your website!
MIT License
Gilded is a tiny JS animation and styling library to add some shine to your website!
It relies heavily on the Promise API for sequencing small atomic changes to page elements, provides methods for manipulating CSS transforms and variables, class manipulation, along with various easing functions and mathematical utility methods, such as a CSS qeuivalent clamp
method or rgbTransform
for color transitions.
This is a browser (not Node.js) module and needs to be bundled with tools such as Webpack or Rollup. You cna install it like so:
$ npm install gilded
Then you'll be able to import the Gilded module and access its API like so:
import g from "gilded"
g.tr()
Creates a transition of specified length (in milliseconds) and calls a callback function
for each animation frame. A promise is returned and can be awaited to sequence multiple
transitions together, with an optional overlap
parameter that specifies a custom resolve time
to allow for overlapping transitions.
// Move div1 box by 100px
await g.tr(1000, t => div1.style.left = `${100*t}px`)
// Resolve div1 after it's just 50% done and start playing div2 immediately:
await g.tr(1000, 500, t => div1.style.left = `${100*t}px`)
await g.tr(1000, t => div2.style.left = `${100*t}px`)
// Apply an easing function:
await g.tr(1000, g.f.easeInQuad, t => div1.style.left = `${100*t}px`)
// Combine easing with overlaps:
await g.tr(1000, 300, g.f.easeInQuad, t => div1.style.left = `${100*t}px`)
await g.tr(1000, g.f.easeInQuad, t => div2.style.left = `${100*t}px`)
g.time()
Returns a promise resolved after a specified amount of time for use in animation sequences to create time gaps.
Accepts an optional callback function for use in the same way as regular setTimeout
,
but with swapped parameters for better readability.
// Create a time gap inside an async function:
console.log('start')
await g.time(1000)
console.log('end')
// Or use as a readable `setTimeout` replacement:
g.time(1000, () => {
console.log('finished')
})
The math (m
) object holds a number of mathematical and color manipulation methods.
g.m.rand()
Returns a random number within boundaries set by min
and max
.
g.m.rand(1, 100) // -> 32, 11, 29, 85, 69, etc...
g.m.avg()
Calculates the average from an array of numbers.
m.avg([20, 40, 60]) // -> 40
g.m.clamp()
Caps the value in a range specified by min
and max
.
This method is a rough implementation of the CSS clamp()
function.
m.clamp(0, -5, 10) // 0
m.clamp(0, 5, 10) // 5
m.clamp(0, 15, 10) // 10
g.m.slide()
Takes the time t
and maps it onto a transition between from
and to
.
m.slide(0.5, 20, 70) // -> 45
m.slide(0.5, 0, -100) // -> -50
g.m.toHex()
Works the same as int.toString(16)
while making sure that the output string is at least 2
characters long and works nicely when put together into a hex color code.
m.toHex(1) // -> 01 (number.toString(16) would leave a single "1")
m.toHex(128) // -. 80
g.m.hexToRgb()
Takes a hex color code and converts it into the RGB CSS function format. Long & shorthand syntax is supported.
m.hexToRGB('#4cddca') // -> rgb(75, 221, 201)
m.hexToRGB('#4cddca80') // -> rgba(75, 221, 201, 0.5)
m.hexToRGB('#fff') // -> rgb(255, 255, 255)
m.hexToRGB('#fff8') // -> rgba(255, 255, 255, 0.53)
g.m.rgbToHex()
Takes an RGB color function and returns a hex code.
m.rgbToHex('rgb(75, 221, 201)') // -> #4cddca
m.rgbToHex('rgba(75, 221, 201, 0.5)') // -> #4cddca88
g.m.hexTransform()
Returns a transition value between two hex color codes based on the progress t
.
Both long and shorthand hex codes are supported, as well as alpha values.
// Using long syntax
m.hexTransform(0.5, '#000000', '#ffffff') // -> #808080
// Using shorthand syntax:
m.hexTransform(0.5, '#000', '#fff') // -> #808080
// Using alpha channel:
m.hexTransform(0.5, '#000000ff', '#ffffff00') // -> #80808080
// Mixing:
// If one of the parameters is an alpha channel, the other one will be treated
// as if it also had an alpha channel, but with opacity set to 1.
m.hexTransform(0.5, '#000000aa', '#888888') // -> #444444d5
// Mixing (long & short syntax):
m.hexTransform(0.5, '#0004', '#888888') // -> #444444a2
g.m.rgbTransform()
Returns a transition value between two rgb
/rgba
color functions based on the progress t
.
Both RGB and RGBA CSS functions can be used interchangeably.
// Using RGB:
m.rgbTransform(0.5, 'rgb(0, 0, 0)', 'rgb(255, 255, 255)') // -> rgb(128, 128, 128)
// Using RGBA:
m.rgbTransform(0.5, 'rgba(0, 0, 0, 1)', 'rgba(255, 255, 255, 0)') // -> rgba(128, 128, 128, 0.5)
// Mixing:
// If one of the parameters is an RGBA function, the other one will also be
// treated as RGBA with opacity of 1.
m.rgbTransform(0.5, 'rgb(0, 0, 0)', 'rgba(255, 255, 255, 0)') // -> rgba(128, 128, 128, 0.5)
Gilded exports a set of easing functions letting you change the behavior of a transition.
Available methods include:
easeInQuad
easeInCubic
easeInQuart
easeInQuint
easeInCirc
easeInExpo
easeOutQuad
easeOutCubic
easeOutQuart
easeOutQuint
easeOutCirc
easeOutExpo
easeInOutQuad
easeInOutCubic
easeInOutQuart
easeInOutQuint
easeInOutCirc
easeInOutExpo
easeOutElastic
easeOutBounce
These methods are can be used to modify the transition curve of the transition
method and can be accessed like so:
const eox = g.f.easeOutExpo
g.transition(1000, eox, t => button.style.left = `${t*100}px`)
The dynamic methods are accessible only after instantiating a Gilded
selector.
That's because these methods aren't simple utility functions. They all produce side-effects
on the selected DOM elements. They manipulate element classes, styles and CSS variables.
You can easily select a number of items like you would when using JQuery.
Additionally, type-safety is provided for all known HTML and SVG element tags like button
, input
, clipPath
, circle
, etc:
const inputs = g('input')
for (let input of inputs) {
// Won't need type casting, as the type is already set to "HTMLInputElement":
input.value
}
You can wrap existing elements and NodeMaps
:
const button = document.getElementById("#myButton")
g(button).addClass('my-class')
const items = document.querySelectorAll("*")
g(items).addClass('my-class')
g().forEach()
Performs the specified action for each selected element.
Direct alias to Array.forEach
.
g('input').forEach((element, index, array) => {
console.log(element, index. array)
})
Optionally, Gilded implements an iterator for use in for of
loops:
for (let input of g('input')) {
console.log(input.value)
}
g().addClass()
Adds a class name to all selected elements.
g('button').addClass('my-class')
g().removeClass()
Removes a class name from selected elements.
g('button').removeClass('my-class')
g().toggleClass()
Toggles a class name on all selected elements.
g('button').toggleClass('my-class')
g().on()
Applies one or more event listeners to all selected elements.
g('button').on('click', (e) => ...)
// or
g('button').on(['mouseenter', 'mouseleave'], (e) => ...)
g().off()
Removes one or more event listeners from all selected elements.
g('button').off('click', callback)
// or
g('button').off(['mouseenter', 'mouseleave'], callback)
The css
Object holds various CSS manipulation methods.
g().css.style()
Applies an inline CSS property to every selected element.
g('button').css.style('color', '#000')
g('button').css.style('border-radius', '10px')
g().css.transform()
Applies a transform function to all selected elements.
Unlike element.style.transform
, it does not affect the already existing transforms,
meaning that changing a property like translateX
won't reset translateY
.
Note: For this method to work properly, all the transforms of the target elements
must be transferred over to an inline style
tag.
g('button').css.toInline('transform')
g('button').css.transform('translateX', '100px')
g().css.toInline()
Transfers the specified computed CSS styles of the target element into its inline style tag. The main use of this method is to avoid bugs when performing transform transitions on elements with external CSS styling.
Example:
// Transfer the computed "transform" style into the
// inline style tag before using "g.transform":
g('button').css.toInline('transform')
g('button').css.transform('translateX', '100px')
g().css.var()
Sets a CSS variable on the target elements.
Starting double-dash (--
) can be omitted and will be handled automatically.
g('button').css.var('size', '20px')
// Would result in
<button style="--size: 20px;"></button>
// Or if you need to set a global variable:
g(document.documentElement).css.var('theme-color', '#ffffff')