buttonizer

v1.0.47

Published

2 months ago

Buttonizer is a small client side utility for enhancing the interactivity of buttons, links, and other clickable elements.

Downloads

184

0High
0Medium
0Low

jackmontfort

This makes buttons good

Buttonizer

Buttonizer is a small client side utility for enhancing the interactivity of buttons, links, and other clickable elements.

It allows you to easily create and assign a pressed state, as well as an on-click animation to your buttons.

It is common practice to simply use the :active pseudo class to apply some styles to approximate a pressed button state, but that solution handles certain edge cases very poorly.

This package is designed to be a better version of that.

Installation

npm install buttonizer

or include index.js directly in your project if you’re not using a bundler.

Usage

//with bundler:
import buttonizer from 'buttonizer';

//without bundler:
import buttonizer from './node_modules/buttonizer/index.js';

const button = document.querySelector('button');
const pressedStyles = { backgroundColor: 'dodgerblue' };
const optionalArgs = {
  hover:{ backgroundColor: 'lightskyblue', outline: '2px solid lightskyblue' },
  focus:{ outline: '2px solid blue' },
  default: {
    borderRadius: '8px',
    border: '1px solid black',
    padding: '12px 24px',
    fontSize: '20px',
    fontWeight: 'bold',
    fontFamily: 'inherit',
    backgroundColor: '#ddf',
    cursor: 'pointer',
    outlineOffset: '4px',
    userSelect: 'none',
    fontFamily: 'sans-serif'
  }
};
const altMode = false;

const clickEffect = {
  duration: '.8s',
  timing: 'ease',
  keyframes: `
    0% { box-shadow: 0 0 0 rgba(212, 0, 255, 0); }
    50% { box-shadow: 0 0 5px 8px rgba(212, 0, 255, 0.95); }
    100% { box-shadow: 0 0 0 rgba(212, 0, 255, 0, 0); }
  `
};
buttonizer(button, pressedStyles, optionalArgs, altMode, clickEffect);

Function Signature

buttonizer(button:Element|String|[], styles:Object /*(optional)*/, optionalArgs: {hover: Object, focus: Ojbect, default: Object} /*(optional)*/, altMode: boolean /*(optional)*/, clickEffect: Object /*(optional)*/);

parameters:

button: Element|String|[].
Designed to be used primarily with button elements, anchors, inputs with type=button|submit|reset, etc. Probably works with lots of other types of elements as well, but not necessarily all of them. See Element Selection for more details.

styles: Optional. JS Style Object.
These are the styles that will be applied to your elements when the button is in a pressed state.

optionalArgs: Optional. Checks for properties named hover, focus, and default, and applies styles accordingly.

  hover: Optional optionalArgs property. JS Style Object.
  These are styles that will be applied to your elements on :hover. This parameter is optional beacuse you could just apply these styles yourself through your own css stylesheet instead of applying them by passing them to buttonizer. This is here for convenience.

  focus: Optional optionalArgs property. JS Style Object.
  Same as above but for :focus.

  default: Optional optionalArgs property. JS Style Object.
  Same as above but these styles will be applied to your elements by default.

altMode: Optional. False by default. If true, will use alt mode. If false, will use normal mode.

clickEffect: Optional. True by default. Adds a temporary visual effect to the button when clicked. Will use a default visual effect if value is true, but animation can be customized by providing an object with duration, timing, and keyframes properties. See usage section for example.

Behavior

Dynamic Class Creation

Each state gets its own unique, auto-generated class name backed by a <style> tag inserted into the document <head>. This avoids collisions and lets you use normal CSS pseudo-classes (:hover, :focus).

Pressed State

Managed through event listeners (pointerdown, pointerup, pointerenter, pointerleave, pointercancel). The pressed class is given extra specificity so it reliably overrides hover and focus states.

Element Selection

If a string is passed instead of an Element, buttonizer tries to resolve it in this order:

querySelectorAll

getElementById

getElementsByClassName

getElementsByName

getElementsByTagName

Example with Multiple Targets

buttonizer(
  [".btn-primary", "#submit", document.querySelectorAll("a.link")],
  { backgroundColor: "tomato" },
  {
    hover:{ backgroundColor: "orange" },
    focus:{ outline: "2px solid red" },
    default:{ border: "1px solid black", padding: "10px 20px" }
  }
);

This applies buttonizer to a mixture of class selectors, an ID, and a NodeList.

Alt Mode

In alt mode, the pressed styles will be applied if you press down the main pointer button and then move it over the button, while in normal mode, they will not.

In other words, alt mode more accurately reflects the state of the input device, while normal mode more accurately reflects those actions that will actually trigger a button click.

Click Effect

If clickEffect is enabled, a visual effect will temporarily appear around the button on click as a visual indicator that the button has been clicked.

Notes

All style objects use JavaScript-style keys (backgroundColor instead of background-color). They are automatically converted into valid CSS.

crypto.randomUUID() is used to generate unique class names.

Working Example

https://stackblitz.com/edit/vitejs-vite-wdieci8p?file=main.js