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

reactive-css-properties

v1.5.7

Published

Set css custom properties and react to changes in realtime from JavaScript

Downloads

30

Readme

Table of contents

The case for re.css

You can think of modern JavaScript having two main responsibilities, updating business logic and updating styling, The trouble with the latter is that this adds extra overhead and new problems to overcome, re.css sets out that it is css's responsibility to update styling and JavaScript should only have a pointer, a way to cheeply make changes, not to elements in the DOM but variables on mass.

CSS-in-JS is not essential with the advent of CSS custom properties (CSS variables), This is because a developer can set and get css custom properties from JavaScript or update existing variables defined in stylesheets, this has important performance and UX implications, reducing the time to first contentful paint and also the amount of work components need to do on update.

JavaScript and CSS can now share data easily and bi-directionally, the result is that styles can remain in stylesheets and JavaScript can continue to add the gloss and sparkles ✨, but that is not enough, we need reactivity.

Why reactive?

If you open devtools and change the value a css variable (other examples: change from a breakpoint or :hover... or anything else), this change happens in realtime, JavaScript is unable to detect this change. So we need a workaround, using re.css reactive-css-properties this now becomes a reality.

How it works?

An observable gets set to watch for style attribute changes of the specified root element, JavaScript can then respond in realtime, diffing the oldValue vs value then calling a function if changes have been detected.

What is the use case?

  • Remove FOUK (flash of un-styled content) forever.
  • Performance benefits over pure CSS-in-JS - cheaper component re-renders
  • Change one variable and have JavaScript set an entire theme's worth of variables.
  • Update a css variable based on screen position or any sensor / event that JavaScript can access that CSS cannot
  • Get CSS variables values and use them in logic
  • Separation of concerns between styling and business logic
  • Dry code
  • SSR support / SSR like styling performance without SSR
  • CSS can be used as configuration which is isomorphic between CSS and JS
  • Encourage developers to think differently and style variables instead of individual elements on the page, it might just change how you create apps and websites

Browser support

As IE11 does not support css custom properties (sort of), at the moment it is not within scope to support IE11, however it may be possible.

Related reading:

Getting started

Installation

yarn add reactive-css-properties --production

# or

npm i reactive-css-properties --only=production

Usage

Set a css custom property.

import rCSSProps from "reactive-css-properties";

// rCSSProps object has no undefined properties and will always yield a class-like callable object.
// The name of your destructured variable is the name of the css variable in snake-case
const { themeTextColor } = rCSSProps();

// insert `--theme-text-color: #000;` into the root element `style` (<html> in this example).
themeTextColor("#000");

// or provide a fallback for browsers which do not support css custom properties
themeTextColor("#000", "#000");

Reacting to css changes

// any themeTextColor calls after this subscription will become reactive
themeTextColor.subscribe((change) => {
  console.log("Im watching for theme text changes", change);
  themeTextBackground('#000');
});

Methods

// Get the full var() to insert into css  
themeTextColor.getUsage();
// Get the key
themeTextColor.getKey();
// Get the value currently, this is not reactive, use subscribe to get realtime values
themeTextColor.getValue();
// Get the fallback value currently, this is not reactive, use subscribe to get realtime values
themeTextColor.getFallbackValue();
// Get scope you optionally provided
themeTextColor.getScope();

reCSSProps constructor details

reCSSProps(element, scopeString);

You can optionally provide an element to set the css variables onto, this provides a scope for this element and its descendants, You can also provide a scope string to prefix all variables with scope, this comes in handy when you have a generated GUID and want to limit the scope to a component. For custom elements, internally the element should be the this keyword, externally the element should be the <custom-element> known as :host.


How to use a reactive variable (optional)

From stylesheets

Use the variable within css, sass or anything which results in css

body {
    color: var(--theme-text-color);
}

You should define the variable before JavaScript has loaded, this is recommended to provide some placeholder styling before JavaScript loads and takes ownership, also to help keep track of variables in use.

:root {
    --theme-text-color: #C0FF33;
}

From JavaScript

CSS-in-JS is not essential, however it is useful, with the workflow described above, you provide styling with or without JavaScript, removing one of the major cases against CSS-in-JS. Using a variable in a string is very simple, cast the variable it to a string, thats it!

const styles = `
    body {
        color: ${themeTextColor};
    }
`

From Typescript

1st class Typescript support for consumers, and our source code is also wrote in TypeScript. The usage is the same as JavaScript and fully typed. Any issues, PR's Welcome!

Use with my favourite framework

  • Vue
  • React - Planned
  • Angular - Planned
  • Lit HTML / Lit Element - Fully supported
  • Not listed? PRs welcome!

Where are the tutorials, examples, perf metrics and style guide?

Its a very high priority to demonstrate the capabilities so you can trust what I am saying. I have used this library before it was released for around a year now, I enjoyed it and imeadiatly saw changes in my workflow and the websites performance as long as I followed my rules. Please keep an eye on the issues section and feel free to pick any of the work up.

Why should I help?

Because I think this project could change the web world for the better and bring new proposals that add new concepts to the Houdini specification... when its ready, It would be a neat project to have on your CV and boost your understanding of CSSOM, browser rendering, TypeScript and bringing a project to release - probably a lot more along the way.

Made with 🧡 and passion for our community by Adam.