npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

slide-element

v2.3.1

Published

A tiny, accessible, Promise-based, jQuery-reminiscent library for hiding and showing elements in a sliding fashion.

Downloads

18,465

Readme

slide-element

Bundle Size

A tiny, accessible, Promise-based, jQuery-reminiscent library for sliding elements with dynamic heights open & closed.

To see it in action, check out the following demos:

Why?

Using JavaScript to animate an element open and closed hasn't traditionally been a straightforward task, especially if it contains dynamically sized content. You could go with something like jQuery's slideToggle(), but that path would require you to take on a lot more code than necessary. Another option is using CSS to change the max-height value of an element, but this approach is filled with arbitrariness and difficult to pull off well when you're not sure how much content you'll be animating over.

This library gets the job done using the Web Animations API, and it doesn't require elements to have fixed heights. Instead, element heights are calculated based on their contents, and then the appropriate values are applied to trigger a smooth, native transition. The animations themselves are powered by the same mechanics used within CSS transitions, making it one of the best ways to pull it off in terms of performance.

It's small, smooth, and focuses on doing one job well: sliding stuff open and closed.

Installation

Run npm install slide-element, or use a CDN like unpkg.

Setup

Make sure your target element is set to display: none;.

Usage

Toggling Elements

Use the toggle function to slide an element open & closed based on its current state.

import { toggle } from "slide-element";

document.getElementById("button").addEventListener("click", (e) => {
  toggle(document.getElementById("box"));
});

Sliding Elements Down

Use the down function to slide an element open.

import { down } from "slide-element";

document.getElementById("button").addEventListener("click", (e) => {
  down(document.getElementById("boxToSlideOpen"));
});

Sliding Elements Up

Use the up function to slide an element closed, and then set its display property to none.

import { up } from "slide-element";

document.getElementById("button").addEventListener("click", (e) => {
  up(document.getElementById("boxToSlideClosed"));
});

Everything's a Promise

Each of the functions provided return promises, so you can easily wait to perform an action after an animation is complete. The resolved value will indicate if the element has just been opened (true), closed (false), or the result of an animation that interruped another (see more below).

import { toggle } from "slide-element";

document.getElementById("button").addEventListener("click", (e) => {
  toggle(document.getElementById("someElement")).then((isOpen: boolean | null) => {
    console.log("Toggling is done!");
  });
});

Interrupting In-Progress Animations

Depending on your settings, some users may be able to repeatedly trigger a new before a previous one has been allowed to finish, which will cause the in-progress animation instantly finish before the new one can begin.

When this occurs, the isOpen Promise that resolves after the animation is complete will return null for each animation that was triggered in interruption of the first. The initial animation, however will still resolve to the correct value. For example, pretend the following animation is clicked rapidly three times in a row.

import { toggle } from "slide-element";

document.getElementById("button").addEventListener("click", (e) => {
  toggle(document.getElementById("someElement")).then((isOpen: boolean | null) => {
    console.log(isOpen);
  });
});

When the animation has been allowed to complete, the following values will be logged -- two null values for the interrupting animations, and one boolean for the initial (and now complete) one. The point here is that it may be necessary to explicitly check for a non-null value when using the resolved "open" state.

true
null
null

Animating Boxes with Padding

If the element you're animating has any padding set to it, be sure to also apply box-sizing: border-box as well. If you don't, the resulting animation will be weird and jumpy.

<div id="myTarget" style="padding: 1rem; box-sizing: border-box; display: none;">
  My contents!
</div>

Customizing the Animation

By default, slide-element uses the following transition property values:

Property | Value -------------------------------------------------------------------------------------------------------- | ------ duration (in milliseconds) | 250 easing (choose one) | ease

You can override these by passing an object as the seceond parameter of any method:

up(document.getElementById("element"), {
  duration: 500,
  easing: "ease-in-out",
});

Customizing the Opened display Value

Out of the box, slide-element will set your opened element to display: block;. If you'd like to customize this, pass a display value as an option:

down(document.getElementById("element"), {
  display: "flex"
});

Customizing the overflow Value Used During Animation

Out of the box, slide-element will animate your element open & closed with overflow: hidden;. If you'd like to pass your own value, use the overflow option:

down(document.getElementById("element"), {
  overflow: "auto"
});

Usage w/o a Bundler

If you'd like to use slide-element directly in the browser via CDN, simply load the code, and then reference the function you'd like to use on the global SlideElement object:

<script src="./path/to/slide-element.js"></script>
<script>
  document.getElementById('someElement').addEventListener('click', (e) => {
    SlideElement.toggle(document.getElementById("someBox"));
});
</script>

API

// Toggle an element based on current state.
toggle(element: HTMLElement, options?: object): Promise<boolean>

// Slide an element down.
up(element: HTMLElement, options?: object): Promise<boolean>

// Slide an element down.
down(element: HTMLElement, options?: object): Promise<boolean>

Param | Type | Description ------- | ------------- | -------------------------------------------- element | HTMLElement | A single HTML node to be slid open or closed options | object | Options to customize sliding animation.

Accessibility

This library will respect the prefers-reduced-motion setting on a user's machine. When it's set to reduce, the sliding animation will be forced to a duration of 0, making the respective elements open and close instantly.

Additionally, it's highly recommended that you toggle the aria-expanded attribute on any element (like a button) that's responsible for triggering an animation. This can be done by adding a single line of code that fires afters an animation is complete:

document.getElementById('someButton').addEventListener('click', (e) => {
    toggle(document.getElementById('thing2')).then((opened) => {

      <!-- Set the appropriate `aria-expanded` value based on the state of the container. -->
      e.target.setAttribute("aria-expanded", opened);
    });
  });

Show Off Your Use Case

I love to see examples of how you're using the stuff I build. If you're comfortable, please send it my way!