compiles Tailwind CSS like shorthand syntax into CSS at runtime
This library takes inspiration from Tailwind CSS (see differences), Oceanwind (see differences), Otion and others to provide means of efficiently generating mostly atomic styles from shorthand syntax and appending them to the DOM at runtime.
Design systems embrace a component-oriented mindset. Inspired by Tailwind CSS, utility classes provide reusable styles with no unwanted side-effects. However, they have to be generated upfront.
Atomicity generalizes the former concept by instantiating style rules on demand. Serving as a solid foundation for constraint-based layouts, atomic CSS-in-JS has come to fluorish at scale.
The library currently weighs ~7kb and supports the vast majority of Tailwind directives and variants (see differences).
Here is a quick example:
// Load an opinionated set of base styles for Tailwind projects.
// If you need to support IE 11 use @beamwind/reset
import preflight from 'https://unpkg.com/@beamwind/preflight'
import { cx, setup } from 'https://unpkg.com/beamwind'
setup(preflight)
<div class={cx`flex space`}>
<div class={cx`w-1/3`}><!-- ... --></div>
<div class={cx`w-1/3`}><!-- ... --></div>
<div class={cx`w-1/3`}><!-- ... --></div>
</div>
npm install beamwind
And then import it:
import { cx } from 'beamwind'
To use the library, first import the module then invoke the cx export using tagged template syntax:
import { cx } from 'https://unpkg.com/beamwind'
document.body.className = cx`h-full bg-purple-500 rotate-3 scale-95`
Running the above code will result in the following happening:
h-full, bg-purple-500, rotate-3, scale-95)h-full -> { height: 100vh }).It is recommended to import the following css files which help normalize styles across browsers:
Importing and invoking beamwind directly will cause it to use
default theme
for directives that require themed values (like bg-primary for example).
The Theming section provides detailed insight into the theming options.
To customize the theme, use the setup export. This will change the theme used by the cx export.
import { cx, setup } from 'beamwind'
setup({
theme: {
colors: {
'red-500': 'hotpink',
},
},
})
cx`bg-red-500` // will result in a hotpink background-color
setupcan be called multiple times where each call extends the existing configuration. Thethemeandpluginsproperties merge their values with the previous ones.
Alternatively you can create a own instance:
import { createInstance } from 'beamwind'
const css = createInstance({
colors: {
'red-500': 'hotpink',
},
})
css`bg-red-500` // will result in a hotpink background-color
Any custom theme will be deep merged with the default theme.
It is possible to invoke beamwind in a multitude of different ways. The cx function can take any number of arguments, each of which can be an Object, Array, Boolean, Number, or String. This feature is based on clsx.
Important: Any falsey values are discarded! Standalone Boolean values are discarded as well.
For example:
// Tag Template Literal (falsey interpolations will be omitted)
cx`bg-primary rounded`
//=> 'bg-primary rounded'
cx`bg-primary ${false && 'rounded'}`
//=> 'bg-primary'
cx`bg-primary ${[false && 'rounded', 'block']}`
//=> 'bg-primary block'
cx`bg-primary ${{ rounded: false, 'text-underline': isTrue() }}`
//=> 'bg-primary text-underline'
// Strings (variadic)
cx('bg-primary', true && 'rounded', 'text-underline')
//=> 'bg-primary rounded text-underline'
// Objects (keys with falsey values will be omitted)
cx({ 'bg-primary': true, rounded: false, 'text-underline': isTrue() })
//=> 'bg-primary text-underline'
// Objects (variadic)
cx({ 'bg-primary': true }, { rounded: false }, null, { 'text-underline': true })
//=> 'bg-primary text-underline'
// Arrays (falsey items will be omitted)
cx(['bg-primary', 0, false, 'rounded'])
//=> 'bg-primary rounded'
// Arrays (variadic)
cx(['bg-primary'], ['', 0, false, 'rounded'], [['text-underline', [['text-lg'], 'block']]])
//=> 'bg-primary rounded text-underline text-lg block'
// Kitchen sink (with nesting)
cx(
'bg-primary',
[1 && 'rounded', { underline: false, 'color-secondary': null }, ['text-lg', ['shadow-lg']]],
'uppercase',
)
//=> 'bg-primary rounded text-lg shadow-lg uppercase'
Directives with the same variants can be grouped using parenthesis. Beamwind will expand the nested directives; applying the variant to each directive in the group before translation. For example:
Notice any directives within tagged template literals can span multiple lines
cx`
sm:hover:(
bg-black
text-white
)
md:(bg-white hover:text-black)
`
// => sm:hover:bg-black sm:hover:text-white md:bg-white md:hover:text-black
It is possible to nest groupings too, for example:
cx`
sm:(
bg-black
text-white
hover:(bg-white text-black)
)
`
// => sm:hover:bg-black sm:hover:text-white sm:hover:bg-white sm:hover:text-black
Object values which are String, Array or Object start a new variant group:
cx({
sm: {
'bg-black': true,
'text-white': true,
hover: 'bg-white text-black',
},
})
// => sm:hover:bg-black sm:hover:text-white sm:hover:bg-white sm:hover:text-black
Two things to note here is that the outermost variant should always be a responsive variant (just like in tailwind
hover:sm:is not supported) and that nesting responsive variants doesn't make sense either, for examplesm:md:is not supported.
beamwind tries to follow a semantic naming approach by using a common language to reduce the guess work. A small set of well known design tokens hopefully prevents magic values or ambiguous names.
The theme object contains keys for screens, colors, and spacing, as well as a key for each customizable core plugin. The default theme shows most of the available values. A tailwind like theme is available via @beamwind/preset-tailwind. For a full featured design system take a look at @beamwind/preset-semantic.
To customize the theme call setup with a theme property:
import { setup } from 'beamwind'
setup({
theme: {
/* ... */
},
})
If the new theme needs to access the existing theme a function can be used:
import { setup } from 'beamwind'
setup({
theme: (theme) => {
return {
colors: {
important: theme.colors.critical,
},
}
},
})
The screens key allows you to customize the responsive breakpoints in your project.
theme = {
screens: {
sm: '576px',
md: '768px',
lg: '992px',
xl: '1200px',
'2xl': '1536px',
},
}
The colors key allows you to customize the global color palette for your project.
By default, these colors are inherited by all color-related core plugins, like borderColor, divideColor, placeholderColor and others.
Note This is a flat object (
{ 'gray-50': '#f9fafb' }) not a nested on like in tailwind (({ 'gray': { 50: '#f9fafb' } })) uses.
Most color directives accept color names (text-rebeccapurple) and hex colors (text-#009900) if the color is not found in theme.colors. This feature should be used for prototyping only as it usually prevents a consistent UI experience.
Out-of-the-box beamwind provides only a few colors that follow the semantic color system and are based on Braid Design System / Tones. @beamwind/preset-tailwind provides the full tailwind color palette.
theme = {
colors: {
current: 'currentColor',
transparent: 'transparent',
none: 'transparent',
surface: '#fff',
'on-surface': '#111',
// https://seek-oss.github.io/braid-design-system/foundations/tones/
primary: '#0d3880',
'on-primary': '#e8ecf4',
secondary: '#e60278',
'on-secondary': '#000',
caution: '#ffc600',
'on-caution': '#1A202C',
critical: '#d0011b',
'on-critical': '#f4e4e6',
info: '#1e468c',
'on-info': '#e8ecf2',
neutral: '#596581',
'on-neutral': '#eaebed',
positive: '#138a08',
'on-positive': '#000',
promote: '#9556b7',
'on-promote': '#f7f5f9',
},
}
Naming colors is one of the most challenging parts of a color system. Many systems try to map color tones to their relative lightness, but this can be problematic because it creates a very loose mental model. Other systems will try to name colors based on use or hierarchy and those are equally problematic.
Most design systems have their own color naming scheme. beamwind does not enforce a particular scheme. With @beamwind/preset-tailwind and @beamwind/preset-semantic two different approaches are available.
surface - affect surfaces of components, such as cards, sheets, and menusprimary - is the color displayed most frequently across screens and componentssecondary - provides more ways to accent and distinguish certain screens and component partscritical - Super important. You need to see this.caution - You should be aware something is happening or mid-way through a process. Could be a risk or an item that needs to be acted upon.positive - Good vibes & new things! Wants to get the user to act on something or be aware something good happened.neutral - Subtle information or details historic in nature. Often already actioned & in the past. No priority required due to the lack of importance or change.info - Guidance & advice. Generally from the UI or business. Functional, calm and non urgent.promote - Things we wish to make prominent and give more visibility to. Typically used to highlight features, updates or marketing messages.provide accessible contrast to their base color -
on-primaryoron-surface
Whenever elements, such as text or icons, appear in front of surfaces, those elements should use colors designed to be clear and legible against the colors behind them. When a color appears "on" top of a primary color, it’s called an "on primary color". They are labelled using the original color category (such as primary color) with the prefix on-.
"On" colors are primarily applied to text, iconography, and strokes. Sometimes, they are applied to surfaces.
The
bg-<color>directive adds a defaultcolorCSS declaration if a correspondingon-*color is found. The reverse works as well:bg-on-<color>addsbg-<color>ascolor. Thecolorset this way can be overridden usingtext-<color>(see Selector Ordering).
The spacing key allows you to customize the global spacing scale for your project.
theme = {
spacing: {
none: '0',
0: '0',
px: '1px',
auto: 'auto',
full: '100%',
base: '.625rem',
xs: '.25rem',
sm: '.5rem',
md: '.875rem',
lg: '1rem',
xl: '1.25rem',
'2xl': '1.5rem',
'3xl': '2rem',
'4xl': '4rem',
'5xl': '5rem',
'6xl': '6rem',
},
}
By default, these values are inherited by the padding, margin, width, height, maxHeight, gap, inset, space, and translate core plugins.
Most tailwind classes use a deterministic number calculation scheme (for example width). If beamwind detects a number in a token and there is not mapped value in the theme it uses the following algorithm to generate a CSS value:
2 or 1.5) are divided by a divisor and rem is used as a unit (w-2.5 becomes width: 0.625rem;)1/6 or 3/5) are evaluated and % is used as a unit (w-4/5 becomes width: 80%;)Non number-like values are used as is and may result in invalid CSS values.
The sizes key allows you to customize the global sizing scale for your project.
theme = {
sizes: {
none: '0',
0: '0',
px: '1px',
auto: 'auto',
full: '100%',
min: 'min-content',
max: 'max-content',
prose: '65ch',
xs: '20rem',
sm: '24rem',
md: '28rem',
lg: '32rem',
xl: '36rem',
'2xl': '42rem',
'3xl': '48rem',
'4xl': '56rem',
'5xl': '64rem',
'6xl': '72rem',
// The screen-\* properties are auto generated from all keys in `screens`
'screen-sm': '576px',
'screen-md': '768px',
'screen-lg': '992px',
'screen-xl': '1200px',
'screen-2xl': '1536px',
},
}
If you also want to provide a default line-height and/or letter-spacing value for a font size, you can do so using a tuple of the form [fontSize, { letterSpacing, lineHeight }].
Conceptual there are two kind of plugins:
{ 'text-color': 'red' })'bg-white text-red')New plugins can be provided using the setup method. setup can be called multiple times where each call extends the existing configuration.
Plugins are searched for by name using the longest prefix before a dash ("-"'). The name and the remaining parts (splitted by a dash) are provided as first argument to the plugin function. For example if the token is bg-gradient-to-t` the following order applies:
| Plugin | Parts |
|---|---|
bg-gradient-to-t | ["bg-gradient-to-t"] |
bg-gradient-to | ["bg-gradient-to", "t"] |
bg-gradient | ["bg-gradient", "to", "t"] |
bg | ["bg", "gradient", "to", "t"] |
Although beamwind provides a pretty comprehensive set of utility classes out of the box, you may run into situations where you need to add a few of your own.
Static utilities can be defined as CSS declaration objects:
import { setup } from 'beamwind'
setup({
plugin: {
'text-important': { color: 'red' },
},
})
Sometimes a pseudo class or child selector maybe required. In these case use an array where the first value is appended to the generated class name in the selector and the second value is CSS declaration object. The next example shows how this can be use to implement a Stretched link:
import { setup } from 'beamwind'
setup({
plugin: {
'stretched-link': [
'::after',
{
position: 'absolute',
top: '0',
right: '0',
bottom: '0',
left: '0',
'z-index': '1',
content: '""',
},
],
},
})
Most utilities have some logic based on the token value or need access to the current theme. For these case you can define a function which needs to return a CSS declaration object, a suffix/declaration tuple or a falsey value if it couldn't handle the provided token parts.
Lets define a basic scroll-snap utility. It should support these tokens: scroll-snap-none, scroll-snap-x and scroll-snap-y
import { setup } from 'beamwind'
setup({
plugins: {
// The token splitted by '-' with the plugin name as first value: ['scroll-snap', ...]
'scroll-snap'(parts) {
return { 'scroll-snap-type': parts[1] }
}
},
},
})
As we are passing the second part through this additionally supports other values like
block,inline,both, ... Note: This may lead to invalid css.
What this currently does not support is something like scroll-snap-both-mandatory. Lets fix that:
// ... same as before
return { 'scroll-snap-type': parts.slice(1).join(' ') }
As this is quite common beamwind provides two helper (join and tail) for this:
import { setup, join, tail } from 'beamwind'
// ... same as before
return { 'scroll-snap-type': join(tail(parts), ' ') }
As a second parameter the plugin function receives a theme value accessor. We can use that to access configured theme values. This allows to provide aliases for token parts. Lets allow these tokens: scroll-snap (using a default value) and scroll-snap-proximity (using a theme value)
import { setup, defaultToKey } from 'beamwind'
setup({
// Add a new theme section; Not needed if you are re-using existing theme sections
theme: {
scroll: {
// eg: 'scroll-snap' => { scroll-snap-type: both; }
DEFAULT: 'both',
// eg: 'scroll-snap-proximity' => { scroll-snap-type: both proximity; }
proximity: 'both proximity',
}
}
plugin: {
'scroll-snap'(parts, theme) {
// defaultToKey: if no theme value is found -> use the provided key (value of parts.slice(1).join(' '))
return { 'scroll-snap-type': theme('scroll', parts.slice(1).join(' '), defaultToKey }
}
}
})
Responsive and state variants (like
hover,focus, ...) are automatically applied. Opposed to tailwind there is no need to define which one should be applied.
Components define a set of utility tokens that should be applied if the component token is used.
Static components that are only a collection of utilities can be defined as strings. The following example allows to use card as a token (cx('card')) which will be expanded to max-w-md mx-auto bg-white rounded-xl shadow-md overflow-hidden md:max-w-2xl:
import { setup } from 'beamwind'
setup({
plugin: {
card: 'max-w-md mx-auto bg-white rounded-xl shadow-md overflow-hidden md:max-w-2xl',
},
})
Dynamic components can be implemented as function which should return a string of tokens to be applied.
import { setup } from 'beamwind'
setup({
plugin: {
btn(parts) {
if (parts[1]) {
return `bg-${parts[1]} text-${parts[1]}-contrast hover:bg-${parts[1]}-hover active:bg-${parts[1]}-active`
} else {
return 'font-bold py-2 px-4 rounded'
}
},
},
})
Some dynamic components depend on additional logic and like to use the familiar cx API. For these case beamwind provides the apply helper, which has the same API signature as cx.
import { setup, apply, optional } from 'beamwind'
setup({
plugin: {
btn(parts, theme) {
if (parts[1]) {
return apply`bg-${parts[1]} text-${parts[1]}-contrast ${{rounded: !!theme('btn', 'rounded', optional}}`
} else {
return 'font-bold py-2 px-4 rounded'
}
}
},
})
beamwind provides a small set of helper functions to write your own plugins:
By default warnings about missing translations will be written to the console.
It is possible to make beamwind throw an error rather just warn by opting into strict mode:
import { setup, fail } from 'beamwind'
setup({ warn: fail })
To fully customize the error handling you can provide a warn function:
setup({
warn: (message, token) => {
/* ... */
},
})
A custom auto-prefixer method may be used as a replacement for the built-in tiny-css-prefixer:
import { setup } from 'beamwind'
import { prefix as stylisPrefix } from 'stylis' // v4
setup({
// A custom solution which weighs more than the default
prefix: (property, value) => stylisPrefix(`${property}:${value};`, property.length).slice(0, -1),
})
beamwind uses hashed class names (like _1m4vcp0) by default. During development or testing it maybe useful to use readable class names:
import { setup } from 'beamwind'
setup({ hash: false })
Alternatively a custom hash function can be provided:
import { setup } from 'beamwind'
import hash from '@emotion/hash'
setup({ hash: (string) => '_' + hash(string) })
An injector is responsible for adding a CSS rule to its underlying target.
During testing or server-side rendering the virtualInjector should be used:
import { cx, setup, virtualInjector } from 'beamwind'
const injector = virtualInjector()
setup({ injector })
injector.target // Array with sorted CSS rulesText
Separate instances of beamwind are necessary when managing styles of multiple browsing contexts (e.g. an <iframe> besides the main document). This option should be used along with a custom target for injection:
import { createInstance, cssomInjector } from 'beamwind'
const iframeDocument = document.getElementsByTagName('iframe')[0].contentDocument
export const { cx } = createInstance({
injector: cssomInjector({
// Make sure this node exists or create it on the fly if necessary
target: iframeDocument.getElementById('beamwind'),
}),
})
Beamwind supports SSR. Consider the following example:
import { h } from 'preact'
import render from 'preact-render-to-string'
import htm from 'htm'
import { createInstance, virtualInjector } from 'beamwind'
import { getStyleTag } from '@beamwind/ssr'
const injector = virtualInjector()
const cx = createInstance({ injector })
const html = htm.bind(h)
const style = {
main: cx`clearfix`,
}
const app = html`<main className=${style.main}>hello beamwind</main>`
const appHtml = render(app)
const styleTag = getStyleTag(injector)
// Inject styleTag to your HTML now.
In order to prevent harmful code injection on the web, a Content Security Policy (CSP) may be put in place. During server-side rendering, a cryptographic nonce (number used once) may be embedded when generating a page on demand:
import { virtualInjector } from 'beamwind'
// Usage with webpack: https://webpack.js.org/guides/csp/
const injector = virtualInjector({ nonce: __webpack_nonce__ })
The same nonce parameter should be supplied to the client-side:
import { setup } from 'beamwind'
setup({ nonce: __webpack_nonce__ })
Changes the destination of the injected rules. By default, a <style id="__beamwind"> element in the ` during runtime, which gets created if unavailable.
To make sure that styles are resolved deterministically the following rules apply in order:
min-width value-:;,#( countingfirst, last, odd, even, link, visited, empty, checked, group-hover, group-focus, focus-within, hover, focus, focus-visible, active, disabled, others - meaning that active overrides focus and hover for example (see When do the :hover, :focus, and :active pseudo-classes apply?- counting - shorthand properties are inserted first eg longhand properties override shorthands.-:;,#(TODO see TODO.md
beamwind uses a different color nameing scheme which is based on Braid Design System - Tones
The default tailwind theme is available via @beamwind/preset-tailwind
import { setup } from 'beamwind'
import tailwindPreset from '@beamwind/preset-tailwind'
setup(tailwindPreset)
`
beamwind is compatible with Tailwind v1 for IE11 support - but trys to integrate new v2 features
The following feature are not yet available in beamwind
most directives are lenient when a value is not found in the theme:
2 or 1.5) are divided by a divisor and a unit is added (w-2.5 becomes width: 0.625rem;)1/6 or 3/5) are evaluated and % is added as a unit (w-4/5 becomes width: 80%;)text-rebeccapurple) and hex colors (text-#009900)d-*: allows to set the display property (from bootstrap)
appearance-*: supports all values
bg-<color>: if a "on" color) (on-<color>) is found it is used as default CSS color; to change to a different color use text-<color> (tailwind style)
border and divide allow to combine positions (top, rrigh, left, bottom)
tr - top & right
brl - top, right and left
Note
xandycan not be combined.
border directives use border shorthand for width, style and color; each of those can be overridden by its variant (border-dashed & border-primary)
border: { border: <theme.borderWidth.DEFAULT> solid <theme.borderColor.DEFAULT>; }border-<position> (border-t or border-l): { border-<position>: <theme.borderWidth.DEFAULT> solid <theme.borderColor.DEFAULT>; }border-<position>-<size> (border-t-xs or border-l-4): { border-<position>: <size> solid <theme.borderColor.DEFAULT>; }border-<position>-<color> (border-t-primary or border-l-red): { border-<position>: <theme.borderWidth.DEFAULT> solid <color>; }border-<position>-<size>-<color> (border-t-xs-primary or border-l-4-red): { border-<position>: <size> solid <color>; }divide directives use border shorthand for width, style and color; each of those can be overridden by its variant (divide-dashed & divide-primary)
divide-<position> (divide-x or divide-y): { border-<position>: <theme.divideWidth.DEFAULT> solid <theme.divideColor.DEFAULT>; }divide-<position>-<size> (divide-x-xs or divide-y-4): { border-<position>: <size> solid <theme.divideColor.DEFAULT>; }divide-<position>-<color> (divide-x-primary or divide-y-red): { border-<position>: <theme.divideWidth.DEFAULT> solid <color>; }divide-<position>-<size>-<color> (divide-x-xs-primary or divide-y-4-red): { border-<position>: <size> solid <color>; }All Tailwind Differences apply aswell.
This library is heavily inspired and based on oceanwind. Without the work of Luke Jackson this would not have been possible! He wrote a great blog post about the development of oceanwind.
Some notable differences are:
beamwind does not generate strictly atomic CSS
Some tailwind classes like font-size are comprised of several CSS declarations. They must be in one CSS declaration block to be overridden by single CSS declarations liken line-heigth.
beamwind supports non configured token values
Most color directives accept color names (text-rebeccapurple) and hex colors (text-#009900) if the color is not found in theme.colors.
Some tailwind classes use a deterministic number calculation scheme (for example width). If beamwind detects a number in a token and there is not mapped value in the theme it uses the following algorithm to generate a CSS value:
decimal numbers (2 or 1.5) are divided by a divisor and a unit is added (w-2.5 becomes width: 0.625rem;)
fractions (1/6 or 3/5) are evaluated and % is added as a unit (w-4/5 becomes width: 80%;)
Non number-like values are used as is and may result in invalid CSS values.
beamwind API additionally supports
cs('bg-blue', 'text-white')beamwind allows to define new plugins (see Plugins)
beamwind adheres to the pseudo class and variant order as used by tailwind
beamwind supports additional tailwind features like
oceanwind supports duplicate token tracking
beamwind is 7-10 times faster than oceanwind (see Beanchmarks)
beamwind is a little bit smaller
| oceanwind | beamwind | |
|---|---|---|
| minified | ||
| gzipped |
All versions of Node.js are supported.
All browsers that support Array.isArray and Object.keys are supported (IE9+).
Without these libraries and their authors this would not have been possible:
This project is free and open-source, so if you think this project can help you or anyone else, you may star it on GitHub. Feel free to open an issue if you have any idea, question, or you've found a bug.
Thanks for being willing to contribute!
Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub
We are following the Conventional Commits convention.
FAQs
ready to go beamwind tailwind theme and preflight
The npm package beamwind receives a total of 72 weekly downloads. As such, beamwind popularity was classified as not popular.
We found that beamwind demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
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.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
