New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

@instructure/ui-themeable

Package Overview
Dependencies
Maintainers
31
Versions
1110
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@instructure/ui-themeable

A UI component library made by Instructure Inc.

  • 7.0.0
  • Source
  • npm
  • Socket score
Version published
Weekly downloads
1.6K
decreased by-17.72%
Maintainers
31
Weekly downloads
 
Created
Source

category: packages

ui-themeable

npm  build-status  MIT License  Code of Conduct

The ui-themeable library is meant to be used along with a babel plugin to import CSS styles and generate theme variables. With this framework, each UI component can be used in isolation and support multiple themes, including dynamic themes provided at runtime, while still working within a system of components that use a shared global theme.

Motivation

  1. Two-tiered theme variable system: system-wide variables + component level variables. With this variable system, components can be themed, tested, and rendered in isolation from the rest of the system, and we can mitigate issues that may arise with system-wide theme updates.

  2. Runtime theme application and definition: to apply user/account level themes without using the CSS cascade.

  3. Prevent CSS Cascade bugs: All components should specify variants via props or component level theme variables only (no className or style overrides) with a clear API and should not rely on any external styles.

  4. Theme variables should be accessible in both JS and CSS.

  5. All component styles and variables should scoped to the component.

  6. Pre-render/server-side render support (inline critical CSS).

Installation

yarn add @instructure/ui-themeable

Usage

Make a UI component themeable:

// Button/index.js
import themeable from '@instructure/ui-themeable'

import styles from 'styles.css'
import theme from 'theme.js'

class Button extends React.Component {
  render () {
    return <button className={styles.root}>{this.props.children}</button>
  }
}
export default themeable(theme, styles)(Example)

Themeable components inject their themed styles into the document when they are mounted.

After the initial mount, a themeable component's theme can be configured explicitly via its theme prop or passed via React context using the ApplyTheme component.

Themeable components register themselves with the global theme registry when they are imported into the application, so you will need to be sure to import them before you mount your application so that the default themed styles can be generated and injected.

Defining variables

The themeable component transforms the JS variables defined in the theme.js file into CSS custom properties that are automatically scoped and applied to the component.

For example, to add a variable for the hover state of a Button component, the theme.js file might contain the following:

// Button/theme.js
export default function generator ({ colors }) {
  return (
    background: colors.backgroundMedium,
    color: colors.textDarkest,

    hoverColor: colors.textLightest,
    hoverBackground: colors.backgroundDarkest
  )
}

The arguments to the generator function are the global theme variables. In the above example, we've defined the default theme for the Button component.

The purpose of the generator function is to take the global variables and apply them as values to the functional component level variables. When coming up with names for the component level variables, try to make them describe how they are used in the component (vs describing the variable value).

Supporting multiple themes

If we want to make the Button transform the global theme variables differently with a another theme, (e.g. canvas-high-contrast) we can make a generator for that theme:

// Button/theme.js
...
generator['canvas-high-contrast'] = function ({ colors }) {
  return {
    background: colors.backgroundLightest
  }
}

This will override the default Button theme and use the global theme variable colors.textLightest for the value of its background theme variable instead of colors.tiara.

The rest of the variables will pick up from the default Button theme generator (applying the global theme variables from the canvas-high-contrast theme).

Using theme variables in CSS

Note: Don't worry about scoping your CSS variables (the ui-themeable library will take care of that for you):

.root {
  background: var(--background);
  color: var(--color);

  &:hover {
    background: var(--hoverBackground);
    color: var(--hoverColor);
  }
}

Using theme variables in JavaScript

Since the variables are defined in JS you can also access them in your component JS (e.g. this.theme.hoverColor) which will give you the theme values applied via React context with ApplyTheme or the theme prop (falling back to the defaults provided in the theme.js file).

How it works

The babel plugin does a few things:

  1. It uses the css-modules-require-hook to namespace the class names (configurable via themeable.config.js).
  2. It runs postcss on the contents of the theme.css file using plugins defined in postcss.config.js, plus postcss-themeable-styles.
  3. It converts the processed CSS string to a function that provides a JS template so that variable values from theme.js can be injected into the CSS for browsers that don't support CSS variables.

The ui-themeable library will call the theme function and inject the resulting CSS string into the document when the component mounts. If the browser supports CSS variables, it will inject namespaced CSS variables into the CSS before adding it to the document.

e.g. The following is injected into the document for browsers with CSS var support:

.list__root {
  color: var(--list__color);
  background: var(--list__background);
}

:root {
  --list__color: #8893A2;
  --list__background: #FFFFFF;
}

Whereas if the browser does not support CSS variables:

.list__root {
  color: #8893A2;
  background: #FFFFFF;
}

The ui-themeable library also supports runtime themes as follows:

For browsers that support CSS variables, it will add variables via the style attribute on the component root (when the theme is changed, either via the theme property or via React context using the ApplyTheme component).

<div style="--list-background: red">

For browsers that don't support CSS variables it will update the DOM like:

<div data-theme="XYZ">
  <style type="text/css">
    [data-theme="XYZ"].list__root {
      background: red;
    }
  </style>
</div>

FAQs

Package last updated on 27 May 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

require(esm) Backported to Node.js 20, Paving the Way for ESM-Only Packages

Security News

require(esm) Backported to Node.js 20, Paving the Way for ESM-Only Packages

require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.

By Sarah Gooding  -  Feb 13, 2025
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc