https://github.com/sagalbot/breeze
💨 A tiny library to transition your DOM elements as they become visible in the viewport.
https://github.com/sagalbot/breeze
animations intersectionobserver tailwindcss transitions
Last synced: 10 months ago
JSON representation
💨 A tiny library to transition your DOM elements as they become visible in the viewport.
- Host: GitHub
- URL: https://github.com/sagalbot/breeze
- Owner: sagalbot
- Created: 2020-10-20T17:21:15.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2022-04-13T15:14:10.000Z (almost 4 years ago)
- Last Synced: 2025-04-11T14:13:14.759Z (10 months ago)
- Topics: animations, intersectionobserver, tailwindcss, transitions
- Language: JavaScript
- Homepage: https://codepen.io/sagalbot/pen/wvWgdjm
- Size: 188 KB
- Stars: 29
- Watchers: 4
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# Breeze 💨
Breeze is a small JavaScript library for transitioning elements into the viewport.
```html
This one will fade in and up over 1000ms with TailwindCSS utility classes.
// Load the library
import { breeze } from "https://unpkg.com/@sagalbot/breeze@latest/dist/breeze.js";
// Transition anything within the body
breeze(document.body);
```
The API design was heavily influenced by TailwindCSS and AlpineJS _(which it works amazing with!)_, but is totally agnostic of any frameworks you might be using. Breeze just needs a root element and the classes you'll use for your transition.
- [Demo](https://breeze.sagalbot.com)
- [CodePen](https://codepen.io/sagalbot/pen/wvWgdjm?editors=1010)
## Install
### NPM
**yarn**
```shell
yarn add @sagalbot/breeze
```
**npm**
```shell
npm i @sagalbot/breeze
```
### CDN
Breeze ships as an ES Module, so you'll need to load it a bit differently than you might be used to.
```html
// Load the library
import { breeze } from "https://unpkg.com/@sagalbot/breeze@latest/dist/breeze.js";
// Transition anything within the body
breeze(document.body);
```
- use the latest version: `https://unpkg.com/@sagalbot/breeze@latest/dist/breeze.js`
- or, you can specify a version: `https://unpkg.com/@sagalbot/breeze@0.4.3/dist/breeze.js`
## Usage / API
### 1. Provide Breeze a root element to initialize.
Breeze will only apply entrance transitions to children of this element.
**NPM/Bundlers**: If you're bundling your code with something like webpack or rollup:
```js
import { breeze } from '@sagalbot/breeze'
breeze(document.body);
```
**CDN**: If you're using the CDN:
```html
// Load the library
import { breeze } from "https://unpkg.com/@sagalbot/breeze@latest/dist/breeze.js";
// Transition anything within the body
breeze(document.body);
```
### 2. Set directives within your HTML.
You'll mainly interact with Breeze via custom attributes on HTMLElements. We'll refer to these as directives.
Breeze has a few directives available:
- `x-breeze-from`: A set of one or more CSS classes that define the starting point for your transition.
- `x-breeze-to`: A set of one or more CSS classes that define the end state for your transition.
**x-breeze-from**
```html
This one will fade in and up over 1000ms with TailwindCSS utility classes.
```
When using `x-breeze-from`, you usually won't need to set an `x-breeze-to` state. `x-breeze-from` classes are added immediately when the element appears in the viewport, and then removed on the next animation frame. In the example above, we don't need to explicitly set `x-breeze-to="opacity-100"` because that is the elements default opacity – as soon as `opacity-0` is removed from the `classList`, the element will being to transition in.
**x-breeze-to**
```html
This one translate down in the viewport as it enters.
```
When using `x-breeze-to` without setting `x-breeze-from`, whatever you set in `class` should be considered the initial state. When the element enters the viewport, the classes in `x-breeze-to` will be added to the element.
## Browser Support
### IntersectionObserver
Breeze uses [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) under the hood to detect when an element has entered the viewport.
IE does not support `IntersectionObserver`, Edge 16 was the first Edge release with support for the API. All the latest versions of Edge, Firefix, Chrome, Safari and Opera all support this API.
[Source: caniuse.com](https://caniuse.com/mdn-api_intersectionobserver)
### ES Module
Breeze ships as an ES module to keep overhead as low as possible. If you're using a build tool like Webpack or Rollup, this won't impact you, but if you're adding the package via CDN, you will need ES module support in the browser. Support for ES modules in the browser is pretty on par with IntersectionObserver.
[Source: caniuse.com](https://caniuse.com/es6-module)