stage set - all of the scenery and props used on stage to create a particular scene

Manage props entering or leaving a scene.

Table of Contents

• Installation
• Usage
• Test
• Contact
• Contributing
• License

Install

NPM:

npm install stageset

CDN:

<script src="https://unpkg.com/stageset/dist/index.umd.js"></script>

Usage

When using modules:

import { onStage } from 'stageset';

Use it like this:

onStage('.scroll-fade').toggle('fade-in');

onStage('#my-element').onScrollProgress((progress, element) => {
	element.style.opacity = progress;
});

✨ View Demo

/**
 * Give it an element or list of elements to get an api object
 * that allows you to trigger actions when an object is scolled into or out of view.
 * @param actors single HTMLElement, Array or query selector string
 * @param options default IntersectionObserver options
 * @example onView('.my-class').toggle('visible')M
 */
function onStage(
	// you can pass elements as: an array, a single element, a css selector string and more; see: https://github.com/CompactJS/uea#doc
	actors: actors: UniversalElementSelector,
	options?: IntersectionObserverOptions
): OnEnterViewAPI;

/**
 * Default IntersectionObserver Options:
 * An optional object which customizes the observer.
 * If options isn't specified, the observer uses the
 * document's viewport as the root, with no margin,
 * and a 0% threshold (meaning that even
 * a one-pixel change is enough to trigger a callback)
 */
interface IntersectionObserverOptions {
	root: HTMLElement;
	rootMargin: string;
	threshold: number | number[];
}

/**
 * Chainable actions when scrolled into or out of view
 */
interface OnViewAPI {
	/**
	 * Add class when scrolled into/out of view
	 * @param className
	 */
	addClass(className: string): OnViewAPI;

	/**
	 * Remove class when scrolled into/out of view
	 * @param className
	 */
	removeClass(className: string): OnViewAPI;

	/**
	 * Toggles a class name when scrolled into/out of view
	 * @param className
	 */
	toggle(className: string): OnViewAPI;

	/**
	 * What to do when scrolled into/out of view
	 * @param fun callback function
	 */
	do(fun: (element: HTMLElement) => void): OnViewAPI;

	/**
	 * Stop observing
	 */
	end(): OnViewAPI;
}

interface OnEnterViewAPI extends OnViewAPI {
	addClass(className: string): OnEnterViewAPI;
	removeClass(className: string): OnEnterViewAPI;
	toggle(className: string): OnEnterViewAPI;
	do(fun: (element: HTMLElement) => void): OnEnterViewAPI;
	end(): OnEnterViewAPI;

	/**
	 * Use it to react to scroll events.
	 * It passed a relative progress variable to the callback function, that will be between 0 and 1.
	 * Everything between 0 and 1 means the element is in the visible area
	 * 0 = below visible area
	 * 1 = above visible area
	 * @param callback
	 */
	onScrollProgress(
		callback: (progress: number, element: HTMLElement) => void
	): OnEnterViewAPI;
	/**
	 * Actions to do when scrolled out of view
	 * Same api as when scrolled into view
	 */
	else: OnLeaveViewAPI;
}
interface OnLeaveViewAPI extends OnViewAPI {
	addClass(className: string): OnLeaveViewAPI;
	removeClass(className: string): OnLeaveViewAPI;
	toggle(className: string): OnLeaveViewAPI;
	do(fun: (element: HTMLElement) => void): OnLeaveViewAPI;
	end(): OnLeaveViewAPI;
}

More examples

// toggle between visible and hidden
onStage('#my-element').toggle('visible').else.toggle('hidden');

// add text when element is visible, only called once
onStage(document.getElementById('my-element')).do(
	(e) => (e.innerHTML += '=> now visible')
);

// add class when elements enter the stage for the first time
onStage('.my-classes').addClass('slide-in');

Also check out the example file.

Run tests

npm run test

Contact

👤 Timo Bechtel

• Website: https://timobechtel.com
• Twitter: @TimoBechtel
• GitHub: @TimoBechtel

🤝 Contributing

Contributions, issues and feature requests are welcome!

1. Check issues
2. Fork the Project
3. Create your Feature Branch (git checkout -b feat/AmazingFeature)
4. Test your changes npm run test
5. Commit your Changes (git commit -m 'feat: add amazingFeature')
6. Push to the Branch (git push origin feat/AmazingFeature)
7. Open a Pull Request

Commit messages

This project uses semantic-release for automated release versions. So commits in this project follow the Conventional Commits guidelines. I recommend using commitizen for automated commit messages.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Distributed under the MIT License.

This README was generated with ❤️ by readme-md-generator