@dash-ui/styles
Advanced tools
A tiny, powerful, framework-agnostic CSS-in-JS library
npm i @dash-ui/styles
div { > * + * { margin-left: 4px; } }Check out an example on CodeSandbox
// React example
import * as React from "react";
import { styles } from "@dash-ui/styles";
// Any global styles or tokens that are inserted into the DOM
// can be easily ejected by calling the function they return.
const flushTokens = styles.insertTokens({
color: {
// var(--color-brand)
brand: "#ee5b5f",
// var(--color-white)
white: "#fafafa",
},
elevation: {
// var(--elevation-resting)
resting:
"0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
},
radius: {
// var(--radius-primary)
primary: "4px",
},
});
const flushGlobal = styles.insertGlobal`
body {
min-height: 100vh;
}
`;
// `styles` is a function for composing style variants in a
// deterministic way. In the example below, you'll see an example
// of a button with default styles and two variants: one for a
// 'brand' background color and one for a 'black' background color.
const button = styles.variants({
// The object in this callback is a mapping to the CSS
// tokens above. `default` here is a special style name
// that will be applied to each invocation of `button()`
default: ({ radius }) => `
display: inline-block;
border: none;
background: transparent;
padding: 0.5rem 1rem;
font-weight: 700;
border-radius: ${radius.primary};
box-shadow: ${elevation.resting};
color: ${color.white};
/**
* Dash uses a CSS preprocessor called stylis so nesting,
* autoprefixing, etc. come out of the box.
* https://www.npmjs.com/package/stylis
*/
:active {
transform: translateY(1px);
}
`,
// Styles can also be defined in the object format
brand: ({ color }) => ({
backgroundColor: color.brand,
}),
// Lastly, styles need not use callbacks if they don't need
// access to design tokens
black: {
backgroundColor: "#000",
},
});
const Component = (props) => (
<div>
{/**
* Styles are composed in the order they're defined in arguments,
* so they are completely deterministic.
*/}
<button className={button("solid", "brand")}>Solid brand</button>
{/**
* That is, in the button below `black`'s background color will
* take precendence over the `brand` background color.
*/}
<button className={button({ outline: true, brand: true, black: true })}>
Solid black
</button>
</div>
);
| Description | |
|---|---|
styles.variants() | styles.variants() is a function for composing style variants in a deterministic way. It returns a function which when called will insert your styles into the DOM and create a unique class name. |
styles.one() | A function that accepts a tagged template literal, style object, or style callback, and returns a function. That function inserts the style into a <style> tag and returns a class name when called. |
styles.cls() | A function that accepts a tagged template literal, style object, or style callback. Calling this will immediately insert the CSS into the DOM and return a unique class name for the styles. This is a shortcut for styles.one({display: 'flex'})(). |
styles.lazy() | A function that uses lazy evalution to create styles with indeterminate values. Calling this will immediately insert the CSS into the DOM and return a unique class name for the styles. |
styles.join() | A function that joins CSS strings, inserts them into the DOM right away, and returns a class name. |
styles.keyframes() | A function that accepts a tagged template literal, style object, or style callback. Using this will immediately insert a global @keyframes definition into the DOM and return the name of the keyframes instance. |
styles.theme() | A function that returns the generated class name for a given theme when using styles.insertThemes() to create CSS variable-based themes. |
styles.insertThemes() | This creates a CSS variable-based theme by defining tokens within a class name selector matching the theme name. Apart from that it works the same way styles.insertTokens() does. This function returns a function that will flush the styles inserted by styles.insertTokens() when it is called. |
styles.insertTokens() | Inserts design tokens into the DOM and makes them available for use in style callbacks. The name of the design tokens is automatically generated based upon the depth of the mapping i.e. foo.bar.baz -> --foo-bar-baz. This function returns a function that will flush the tokens that were inserted when it is called. |
styles.insertGlobal() | A function that accepts a tagged template literal, style object, or style callback. Using this will immediately insert styles into the DOM relative to the root document. This function returns a function that will flush the styles inserted when it is called. |
styles.hash() | The hashing function used for creating unique selector names. |
styles.tokens | The design tokens configured in the instance. |
styles.dash | The instance of underlying the Dash cache used by this instance. This was automatically created by createDash() when createStyles() was called. Dash controls the caching, style sheets, auto-prefixing, and DOM insertion that happens in the styles.variants() instance. |
Dash has robust server rendering utilities out of the box. If you're using React, there
are even more helpers available for Gatsby, Next.js, etc. available in
@dash-ui/react.
| Description | |
|---|---|
createStylesFromCache() | Creates a string of CSS based on the dash inserted cache. This is an extremely fast way to generate a CSS string. It returns an object containing the hash names of all of the styles used as well as the CSS string. Note that this function is unsafe in asynchronous render environments because multiple pages using the same cache will dirty the results. This means it will not work with Gatsby, for example. |
createStyleTagFromCache() | Creates a <style> tag w/ CSS based on the dash inserted cache. This is an extremely fast way to generate a <style> tag. Note that this function is unsafe in asynchronous render environments because multiple pages using the same cache will dirty the results. This means it will not work with Gatsby, for example. |
writeStylesFromCache() | Writes a CSS to a file based on the dash inserted cache. This is an extremely fast way to generate a CSS file. Note that this function is unsafe in asynchronous render environments because multiple pages using the same cache will dirty the results. This means it will not work with Gatsby, for example. |
createStylesFromString() | Creates a string of CSS based on an HTML string. This function will parse your HTML output for Dash class names and pull the styles associated with them from the Dash cache. It returns an object containing the hash names of all of the styles used as well as the CSS string. This is a safe way to generate style strings in an asynchronous environment. |
createStyleTagFromString() | Creates a <style> tag w/ CSS based on an HTML string. This function will parse your HTML output for Dash class names and pull the styles associated with them from the Dash cache. This is a safe way to generate <style> tags in an asynchronous environment. |
writeStylesFromString() | Writes a CSS to a file based on an HTML string. This function will parse your HTML output for Dash class names and pull the styles associated with them from the Dash cache. This is a safe way to generate CSS files in an asynchronous environment. |
styles instance| Description | |
|---|---|
createStyles() | A factory function that returns a new styles instance with your custom configuration options. |
createDash() | Dash is a tiny, performant CSS-in-JS style rule sheet manager similar to Emotion. |
| Description | |
|---|---|
compileStyles() | A utility function that will compile style objects and callbacks into CSS strings. |
hash() | An FNV-1a hashing algorithm with a 32-bit offset basis. FNV-1a hashes are designed to be fast while maintaining a low collision rate. The high dispersion rate makes them well-suited for hashing nearly identical strings. This is the default hash used by createStyles(). |
Dash is written in TypeScript. It's also strongly typed, creating a beautiful IntelliSense experience in VSCode and providing solid insurance to your TypeScript application.
| Description | |
|---|---|
| Strongly typed tokens | Learn how to add autocomplete and type safety to your design tokens. |
| Strongly typed themes | Learn how to add autocomplete and type safety to your CSS variable themes. |
Write something awesome for Dash, tell me about it, and I will put it here.
| Description | |
|---|---|
@dash-ui/layout | Framework-agnostic layout primitives for @dash-ui. |
@dash-ui/jest | The easiest way to test React, Preact, and Preact X components with @dash-ui. This includes snapshot serialization and a custom Jest matcher. |
@dash-ui/react | React components and hooks for @dash-ui. |
@dash-ui/react-layout | Layout primitives for React and @dash-ui, including Box, Cluster, Grid, Row, Column, and Layer. |
@dash-ui/mq | A utility function for adding stored media queries and breakpoints to @dash-ui styles. |
@dash-ui/transition | A library for creating performant and composable CSS transitions with @dash-ui. |
In the days before Emotion was subsumed by the React community and effectively ruined, there existed a beautiful, simple CSS-in-JS API. It returned class names instead of objects. It was easy to use. It didn't require a babel plugin or a JSX pragma. It wasn't inextricably tied to React or React context trees.
About a year after I created that Emotion issue, I started work on Dash. I've worked tirelessly since to create a library I genuinely liked using. I wanted to create a library that combined the simplicity of CSS with the versatility of JavaScript - as CSS-in-JS has always intended.
Dash can be used in React, but doesn't rely on it. It can also be used in Vue, Svelte, and anywhere else you can use JavaScript. Themes are created with CSS variables and selectors, not React context.
I hope you'll give it a chance.
styles.variants() is a function for composing style variants in a deterministic way. It returns a
function which when called will insert your styles into the DOM and create a unique class name.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { styles } from "@dash-ui/styles";
const button = styles.variants({
// The object in this callback is a mapping to the CSS
// tokens above. `default` here is a special style name
// that will be applied to each invocation of `button()`
default: ({ radius }) => `
display: inline-block;
border: none;
background: transparent;
padding: 0.5rem 1rem;
font-weight: 700;
border-radius: ${radius.primary};
box-shadow: ${elevation.resting};
:active {
transform: translateY(1px);
}
`,
// Styles can also be defined in the object format
primary: ({ color }) => ({
backgroundColor: color.primary,
color: color.white,
}),
// Lastly, styles need not use callbacks if they don't need
// access to design tokens
black: {
backgroundColor: "#000",
color: "#fff",
},
});
const Component = (props) => (
<React.Fragment>
{/**
* Styles are composed in the order they're defined in arguments,
* so they are completely deterministic. Calling the `button`
* function returns a string class name.
*/}
<button className={button("solid", "brand")}>Solid brand</button>
{/**
* That is, in the button below `black`'s background color will
* take precendence over the `brand` background color because it
* is declared after `brand`.
*/}
<button className={button({ outline: true, brand: true, black: true })}>
Solid black
</button>
</React.Fragment>
);
styles<N extends string>(styleMap: StyleMap<N, V>): Style<N, V>
| Argument | Type | Required? | Description |
|---|---|---|---|
| styleMap | StyleMap | Yes | A key/CSS value mapping |
/**
* A function that inserts styles from the style map into the DOM when called
* with those style names selected.
*
* @param args A series of style names or style name/boolean maps which
* select the styles from the style map you want to compose into a singular
* deterministic style and class name.
*/
export type Style<N extends string, V extends DashTokens = DashTokens> = {
(...args: StyleArguments<N>): string;
/**
* A function that returns the raw, CSS string for a given
* name in the style map.
*
* @param names A series of style names or style name/boolean maps which
* select the styles from the style map you want to compose into a singular
* CSS string.
*/
css(...names: StyleArguments<N>): string;
/**
* The style map that this `style()` instance was instantiated with.
*/
styles: StyleMap<N, V>;
};
export type StyleArguments<N extends string> = (
| N
| {
[Name in N]?: boolean | null | undefined | string | number;
}
| Falsy
)[];
export type StyleMap<N extends string, V extends DashTokens = DashTokens> = {
[Name in N | "default"]?: StyleValue<V>;
};
export type StyleValue<V extends DashTokens = DashTokens> =
| string
| StyleCallback<V>
| StyleObject;
export type StyleObject = {
[property: string]: StyleObject | string | number;
};
export type StyleCallback<V extends DashTokens = DashTokens> = (
tokens: V
) => StyleObject | string;
A function that accepts a tagged template literal, style object, or style callback, and
returns a function. That function inserts the style into a <style> tag and returns a
class name when called.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { styles } from "@dash-ui/styles";
// Can be a tagged template literal
const heading = styles.one`
font-size: 2rem;
font-weight: bold;
`;
// Or an object
const heading = styles.one({
fontSize: "2rem",
fontWeight: "bold",
});
// Or a callback
const heading = styles.one(({ font }) => ({
fontSize: font.size.heading,
fontWeight: "bold",
}));
const Heading = () => <h1 className={heading()}>Hello world</h1>;
/**
* A function that inserts styles into the DOM when called without
* a falsy value. If the first argument is falsy, the styles will
* not be inserted and a class name will not be returned.
*/
export type StylesOne = {
(createClassName?: boolean | number | string | null): string;
/**
* A method that returns a CSS string if the first argument is not falsy.
*/
css(createCss?: boolean | number | string | null): string;
};
A function that accepts a tagged template literal, style object, or style callback.
Calling this will immediately insert the CSS into the DOM and return a unique class
name for the styles. This is a shortcut for styles.one({display: 'flex'})().
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { styles } from "@dash-ui/styles";
// The styles here will only be injected into the DOM
// immediately when the style is created. This is cached
// so it will only happen on the first call. Any
// subsequent calls merely return a class name.
const Box = () => (
<div
className={styles.cls(
({ color }) => `
width: 200px;
height: 200px;
background-color: ${color.primary};
:hover {
background-color: ${color.secondary};
}
`
)}
/>
);
string; // A class name
A function that uses lazy evalution to create styles with indeterminate values. Calling this will immediately insert the CSS into the DOM and return a unique class name for the styles.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import clsx from "clsx";
import { styles } from "@dash-ui/styles";
// The lazy function can return style objects, style callbacks,
// and strings
const bgColor = styles.lazy((colorName) => ({ color }) => ({
backgroundColor: color[colorName],
}));
const Box = ({ bg = "primary" }) => <div className={bgColor(bg)} />;
/**
* A function that inserts indeterminate styles based on the value
* into the DOM when called.
*
* @param value A JSON serializable value to create indeterminate
* styles from
*/
export type StylesLazy<Value extends LazyValue> = {
(value?: Value): string;
/**
* A method that returns indeterminate CSS strings based on the value
* when called.
*
* @param value A JSON serializable value to create indeterminate
* styles from
*/
css(value?: Value): string;
};
A function that joins CSS strings, inserts them into the DOM right away, and returns a class name.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { styles } from "@dash-ui/styles";
// Create a style for primary bg color
const bgPrimary = styles.one(
({ color }) => `
background-color: ${color.primary};
`
);
// Creates styles for a box with 2 widths
const box = styles.variants({
default: {
width: 200,
height: 200,
},
big: {
width: 400,
height: 400,
},
});
// This joins CSS strings together and immediately
// inserts them into the DOM while returning a
// class name
const PrimaryBox = () => (
<div className={styles.join(bgPrimary.css(), box.css("big"))} />
);
styles.join(...css: string[]): string
| Argument | Type | Required? | Description |
|---|---|---|---|
| ...css | string[] | Yes | One or several CSS strings you want to join into one style |
string; // A class name
A function that accepts a tagged template literal, style object, or style callback. Invoking it will immediately inject its styles into the DOM and return an animation name which can then be referenced in other styles.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { styles } from "@dash-ui/styles";
// Immediately injects keyframes styles into the
// DOM and returns an animation name which can then
// be referenced in other styles.
const zoomy = styles.keyframes`
0% {
transform: scale(0.0);
}
60% {
transform: scale(1.4);
}
80% {
transform: scale(1);
}
100% {
transform: scale(0.0);
}
`;
// Creates styles for a zoomy box
const zoomyBox = styles.one({
animationName: zoomy,
animationDuration: `2000ms`,
animationIterationCount: "infinite",
backgroundColor: "#008489",
width: 100,
height: 100,
margin: "48px auto",
});
const ZoomyBox = () => <div className={zoomyBox()} />;
string; // An animation name
A function that returns the generated class name for a given theme when using
styles.insertThemes() to create CSS variable-based themes.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { createStyles } from "@dash-ui/styles";
// Creating our own styles instance gives us strong
// types for `themes` and `tokens` without having
// to declare DashTokens and DashThemes types in
// our app
const styles = createStyles({
themes: {
// Light mode design tokens
light: {
bgColor: "#FAFAFA",
primaryColor: "#ee5b5f",
},
// Dark mode design tokens
dark: {
bgColor: "#272727",
primaryColor: "#333",
},
} as const,
});
export const App = () => {
const [mode, setMode] = React.useState<"light" | "dark">("light");
React.useEffect(() =>
styles.insertGlobal(({ bgColor }) => ({
body: { backgroundColor: bgColor },
}))
);
return (
// Sets the theme name on the body element
// The theme class name is what determines
// which CSS variable values take precedence
// in the cascade
<body className={styles.theme(mode)}>
<div
className={styles.cls(
({ bgColor, primaryColor }) => `
width: 200px;
height: 200px;
background-color: ${primaryColor};
`
)}
/>
<button
onClick={() => setMode((mode) => (mode === "light" ? "dark" : "light"))}
>
Switch to {mode === "light" ? "dark" : "light"} mode
</button>
</body>
);
};
theme(name: T): string
| Argument | Type | Required? | Description |
|---|---|---|---|
| name | string | Yes | The name of the theme |
string; // A class name
This creates a CSS variable-based theme by defining tokens within a class name selector
matching the theme name. Apart from that it works the same way
styles.insertTokens() does. This function returns a
function that will flush the styles inserted by styles.insertTokens()
when it is called.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { createStyles } from "@dash-ui/styles";
// Creating our own styles instance gives us strong
// types for `themes` and `tokens` without having
// to declare DashTokens and DashThemes types in
// our app
const styles = createStyles({
themes: {
// Light mode design tokens
light: {
primaryColor: "#ee5b5f",
},
// Dark mode design tokens
dark: {
primaryColor: "#272727",
},
},
});
export const App = () => {
const [mode, setMode] = React.useState<"light" | "dark">("light");
const [darkModePrimary, setDarkModePrimary] = React.useState("#272727");
const [lightModePrimary, setLightModePrimary] = React.useState("#ee5b5f");
React.useEffect(
// Here we are updating our theme values each
// time they change for a given mode.
() =>
styles.insertThemes({
light: {
primaryColor: lightModePrimary,
},
dark: {
primaryColor: darkModePrimary,
},
}),
[darkModePrimary, lightModePrimary]
);
return (
// Sets the theme name on the body element
// The theme class name is what determines
// which CSS variable values take precedence
// in the cascade
<body className={styles.theme(mode)}>
<div
className={styles.cls(
({ primaryColor }) => `
width: 200px;
height: 200px;
background-color: ${primaryColor};
`
)}
/>
<div>
<button
onClick={() =>
setMode((mode) => (mode === "light" ? "dark" : "light"))
}
>
Switch to {mode === "light" ? "dark" : "light"} mode
</button>
</div>
<label>
<h4>Light mode primary color</h4>
<input
value={lightModePrimary}
onChange={(e) => setLightModePrimary(e.target.value)}
/>
</label>
<label>
<h4>Dark mode primary color</h4>
<input
value={darkModePrimary}
onChange={(e) => setDarkModePrimary(e.target.value)}
/>
</label>
</body>
);
};
insertThemes(
themes: DeepPartial<
{
[Name in DashThemeNames]: DashTokens
}
>
): () => void
| Argument | Type | Required? | Description |
|---|---|---|---|
| themes | DeepPartial<{[Name in DashThemeNames]: DashTokens}> | Yes | A mapping of theme name/CSS variable pairs. |
// A function that flushes the style sheet created by
// inserting the new variable values when invoked
() => void
Inserts design tokens into the DOM and makes them available for use in style callbacks. The
name of the design tokens is automatically generated based upon the depth of the mapping
i.e. foo.bar.baz -> --foo-bar-baz. This function returns a function that will flush
the tokens that were inserted when it is called.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { createStyles } from "@dash-ui/styles";
// Creating our own styles instance gives us strong
// types for `tokens` without having to declare
// DashTokens in our app
const styles = createStyles({
tokens: {
primaryColor: "#ee5b5f",
},
});
export const App = () => {
const [primaryColor, setPrimaryColor] = React.useState("#ee5b5f");
React.useEffect(
// Here we are updating our variable values each
// time they change.
() =>
styles.insertTokens({
primaryColor,
}),
[primaryColor]
);
return (
<div>
<div
className={styles.cls(
({ primaryColor }) => `
width: 200px;
height: 200px;
background-color: ${primaryColor};
`
)}
/>
<label>
<h4>Primary color</h4>
<input
value={primaryColor}
onChange={(e) => setPrimaryColor(e.target.value)}
/>
</label>
</div>
);
};
insertTokens(tokens: DeepPartial<DashTokens>, selector?: string): () => void
| Argument | Type | Required? | Default | Description |
|---|---|---|---|---|
| tokens | DeepPartial<DashTokens> | Yes | A map of CSS variable name/value pairs | |
| selector | string | No | ":root" | Including a selector will only make these CSS variable definitions take effect within the selector, e.g. a class name or ID. |
// A function that flushes the style sheet created by
// inserting the new variable values when invoked
() => void
A function that accepts a tagged template literal, style object, or style callback. Using this will immediately insert styles into the DOM relative to the root document. This function returns a function that will flush the styles inserted when it is called.
Play with an example on CodeSandbox
// React example
import * as React from "react";
import { styles } from "@dash-ui/styles";
const flushStyles = styles.insertGlobal({
body: {
minHeight: "100vh",
backgroundColor: "#ee5b5f",
color: "#fff",
fontFamily: "Inter, -apple-system, sans-serif",
},
h1: {
margin: "1rem",
fontSize: "3rem",
},
});
export const App = () => {
return (
<div>
<h1>Hello world</h1>
<button onClick={flushStyles}>Flush styles</button>
</div>
);
};
// A function that flushes the style sheet created when
// inserting the new global styles
() => void
The hashing function used for creating unique selector names. This can be
configured by creating your own styles instance with createStyles().
import { styles } from "@dash-ui/styles";
console.log(styles.hash("foo: bar;"));
// 1rcc4tl
hash(string: string): string
| Argument | Type | Required? | Description |
|---|---|---|---|
| string | string | Yes | The string you'd like to hash |
string; // A hash of the input string
The design tokens configured in the instance
import {styles} from '@dash-ui/styles`
styles.insertTokens({foo: 'bar'})
console.log(styles.tokens)
// {foo: 'var(--foo)'}
The instance of underlying the Dash cache used by this instance. This was automatically
created by createDash() when createStyles() was called.
Dash controls the caching, style sheets, auto-prefixing, and DOM insertion that happens
in the styles instance.
import { styles } from "@dash-ui/styles";
// Inserts a style named 'foo' under the selector '.foo'
// into the default style sheet
styles.dash.insert("foo", ".foo", "display: flex;");
A factory function that returns a new styles instance with your custom configuration options.
I would suggest that you almost always create your own styles instance - especially when
using TypeScript.
import {createStyles, createDash} from '@dash-ui/styles`
const styles = createStyles({
dash: createDash({key: 'css', prefix: false}),
mangleTokens: typeof process !== 'undefined' && process.env.NODE_ENV === 'production',
tokens: {
gap: {
sm: '0.25rem',
md: '0.5rem',
lg: '1rem'
}
}
})
const oneStyle = styles.one(({gap}) => `
margin: ${gap.md};
`)
function createStyles<
V extends DashTokens = DashTokens,
T extends string = DashThemeNames
>(options: CreateStylesOptions<V, T> = {}): Styles<V, T>;
| Argument | Type | Required? | Description |
|---|---|---|---|
| options | CreateStylesOptions | No | Configuration options |
A new styles instance
Styles<V, T>
| Option | Type | Required? | Default | Description |
|---|---|---|---|---|
| dash | Dash | No | createDash() | An instance of Dash created by the createDash() factory |
| tokens | DashTokens | No | Inserts design tokens into the DOM and makes them available for use in style callbacks. The name of the design tokens is automatically generated based upon the depth of the mapping i.e. foo.bar.baz -> --foo-bar-baz. | |
| themes | DashThemes | No | A mapping of theme name/CSS variable pairs. This Creates a CSS variable-based theme by defining tokens within a class name selector matching the theme name. Apart from that it works the same way tokens does. | |
| mangleTokens | boolean | {[key: string]: boolean} | No | false | When true this will mangle CSS variable names. You can also provide an object with {key: boolean} pairs of reserved keys which will not be mangled. |
| hash | (string: string) => string | No | hash | Use your own hash function for creating selector names. By default Dash uses an fnv1a hashing algorithm. |
Dash is a tiny, performant CSS-in-JS style rule sheet manager similar to Emotion.
import { createDash } from "@dash-ui/styles";
const dash = createDash({ key: "css", prefix: false });
// Inserts a style named 'flex' under the selector '.flex'
// into the default style sheet
dash.insert("flex", ".flex", "display: flex;");
function createDash(options: CreateDashOptions = {}): Dash;
| Argument | Type | Required? | Description |
|---|---|---|---|
| options | CreateDashOptions | No | Configuration options |
// An instance of Dash
export type Dash = {
/**
* The sheet key
*/
readonly key: string;
/**
* The default style sheet used by this instance of Dash
*/
readonly sheet: DashStyleSheet;
/**
* Used for tracking external sheets. You can safely add/delete new
* custom sheets using this. Those sheets can be used in the `insert()`
* method. The primary reason you'd want to use this is so that you can
* create independently flushable styles/sheets.
*/
readonly sheets: DashSheets;
/**
* The instance of Stylis used by this Dash instance
*/
readonly stylis: typeof Stylis;
/**
* A cache of Stylis rules saved by their keys. This is only used
* on the server for generating CSS files and strings from the keys
* used in the cache.
*/
readonly cache: Map<string, string>;
/**
* A function for inserting style rules into the document and cache.
*
* @param key The unique key of the rule. This is used for caching.
* @param selector The CSS selector to insert the rule under. Omit this
* when inserting a global style.
* @param styles The rules string you'd like to insert into the document or cache.
* @param styleSheet The style sheet to insert a rule into, for example `dash.sheet`.
*/
insert(
key: string,
selector: string,
styles: string,
styleSheet?: DashStyleSheet
): void;
/**
* An insertion cache. This tracks which keys have already been inserted into
* the DOM to prevent duplicates.
*/
readonly inserted: Set<string>;
};
| Option | Type | Required? | Default | Description |
|---|---|---|---|---|
| key | string | No | "ui" | Keys in sheets used to associate <style> tags with this specific Dash instances via the dash-cache property. This is also used as a class name prefix in styles. |
| nonce | string | No | For security policies. A nonce is an arbitrary number that can be used just once in a cryptographic communication. | |
| stylisPlugins | Plugable[] | No | An array of Stylis plugins. See: https://www.npmjs.com/package/stylis | |
| prefix | boolean | ((key: string, value: any, context: any) => boolean) | No | true | Turns on/off vendor prefixing. When a boolean, all prefixes will be turned on/off. Use a function to define your own prefixes for a given key/value. |
| container | HTMLElement | No | document.head | This is the container that <style> tags will be injected into when style rules are inserted. |
A utility function that will compile style objects and callbacks into CSS strings.
import { compileStyles } from "@dash-ui/styles";
const css = compileStyles({
display: "flex",
"> * + *": {
marginLeft: "0.5rem",
},
});
console.log(css);
// "display:flex;> * + *{margin-left:0.5rem;}"
const red = compileStyles(({ red }) => ({ color: red }), { red: "var(--red)" });
console.log(red);
// "color:var(--red);"
| Argument | Type | Required? | Description |
|---|---|---|---|
| styles | StyleValue<V> | Falsy | Yes | A style callback, object, or string |
| tokens | DashTokens | No | A map of design tokens for style callbacks |
string; // A CSS string
An FNV-1a hashing algorithm with a 32-bit offset basis. FNV-1a hashes are designed to be
fast while maintaining a low collision rate. The high dispersion rate makes them
well-suited for hashing nearly identical strings. This is the default hash used by
createStyles().
import { hash } from "@dash-ui/styles";
console.log(hash("foo: bar;"));
// 1rcc4tl
function hash(string: string): string;
| Argument | Type | Required? | Description |
|---|---|---|---|
| string | string | Yes | The string you'd like to hash |
string; // A hash of the input string
Creates a string of CSS based on the Dash inserted cache. This is an extremely fast
way to generate a CSS string. It returns an object containing the hash names of
all of the styles used as well as the CSS string.
Note that this function is unsafe in asynchronous render environments because multiple pages using the same cache will dirty the results. This means it will not work with Gatsby, for example.
import { styles } from "@dash-ui/styles";
import { createStylesFromCache } from "@dash-ui/styles/server";
// Inserts a new class for `display: flex;`
styles.cls`display: flex;`;
// Reads from the cache
const { css, names } = createStylesFromCache(styles);
// A CSS string generated from the cache
console.log(css);
// ".ui-1ut9bc3{display:flex;}"
// A list of all of the names that were in the cache
console.log(names);
// ["1ut9bc3"]
export function createStylesFromCache(
styles = require("@dash-ui/styles").styles,
options: CreateServerStylesOptions = {}
): ServerStylesResult;
| Argument | Type | Required? | Default | Description |
|---|---|---|---|---|
| styles | styles | No | styles | A styles instance |
| options | CreateServerStylesOptions | No | {clearCache: false} | Configuration options |
export interface ServerStylesResult {
/**
* A CSS string containing all of the styles that were used
*/
css: string;
/**
* Hash names of all of the styles used in the generated CSS
*/
names: string[];
}
| Option | Type | Required? | Default | Description |
|---|---|---|---|---|
| clearCache | boolean | No | false | Clears the Dash inserted cache after styles have been generated. This is useful in synchronous environments when you only want to generate CSS strings for the styles that were actually used in a given page/render. |
Creates a <style> tag w/ CSS based on the dash inserted cache. This is an
extremely fast way to generate a <style> tag.
Note that this function is unsafe in asynchronous render environments because multiple pages using the same cache will dirty the results. This means it will not work with Gatsby, for example.
import { styles } from "@dash-ui/styles";
import { createStyleTagFromCache } from "@dash-ui/styles/server";
// Inserts a new class for `display: flex;`
styles.cls`display: flex;`;
// Reads from the cache
const styleTag = createStyleTagFromCache(styles);
// A <style> tag generated from the cache
console.log(styleTag);
// "<style data-dash=\"1ut9bc3\" data-cache=\"ui\">.ui-1ut9bc3{display:flex;}</style>"
export function createStyleTagFromCache(
styles = require("@dash-ui/styles").styles,
options: CreateServerStylesOptions = {}
): string;
| Argument | Type | Required? | Default | Description |
|---|---|---|---|---|
| styles | styles | No | styles | A styles instance |
| options | CreateServerStylesOptions | No | {clearCache: false} | Configuration options |
string; // A <style> tag with css generated from the cache
Writes a CSS to a file based on the dash inserted cache. This is an extremely fast
way to generate a CSS file.
Note that this function is unsafe in asynchronous render environments because multiple pages using the same cache will dirty the results. This means it will not work with Gatsby, for example.
import { styles } from "@dash-ui/styles";
import { writeStylesFromCache } from "@dash-ui/styles/server";
// Inserts a new class for `display: flex;`
styles.cls`display: flex;`;
// Reads from the cache
writeStylesFromCache("../public/css", styles).then(
({ filename, css, names }) => {
// The filename where the file was written
console.log(filename);
// "../public/css/ui-115aj09.css"
// A CSS string generated from the cache
console.log(css);
// ".ui-1ut9bc3{display:flex;}"
// A list of all of the names that were in the cache
console.log(names);
// ["1ut9bc3"]
}
);
async function writeStylesFromCache(
outputPath = "",
styles = require("@dash-ui/styles").styles,
options?: WriteStylesOptions & { clearCache?: boolean }
): Promise<WriteServerStylesResult>;
| Argument | Type | Required? | Default | Description |
|---|---|---|---|---|
| outputPath | string | No | "" | An absolute or relative path dictating where you want to output the CSS file. |
| styles | styles | No | styles | A styles instance |
| options | WriteServerStylesOptions & CreateServerStylesOptions | No | {clearCache: false} | Configuration options |
export interface WriteServerStylesResult {
/**
* The filename of the generated file. This is the `outputPath` joined
* to the basename of the CSS file that was generated.
*/
filename: string;
/**
* The basename of the CSS file that was generated.
*/
name: string;
/**
* The output path of the CSS file excluding the basename.
*/
path: string;
/**
* The CSS string that was generated and written to the output
* file.
*/
css: string;
/**
* The hash names of all of the styles that were inserted into
* the generated CSS string.
*/
names: string[];
}
| Option | Type | Required? | Description |
|---|---|---|---|
| name | string | No | Use this if you want to create your own name for the CSS file. By default, this function will create a filename based on the hash of the generated CSS string and the key in Dash. |
| hash | (string: string) => string | No | Use a custom hash function for creating the name of your CSS file. By default this function will use the hash function attached to your styles instance. |
Creates a string of CSS based on an HTML string. This function will parse your HTML output for Dash class names and pull the styles associated with them from the Dash cache. It returns an object containing the hash names of all of the styles used as well as the CSS string.
This is a safe way to generate style strings in an asynchronous environment.
import { styles } from "@dash-ui/styles";
import { createStylesFromString } from "@dash-ui/styles/server";
// Inserts a new class for `display: flex;`
styles.cls`display: flex;`;
// This function will match names in the style cache against
// class names found in your HTML string. It will create CSS
// from the names it finds.
const { css, names } = createStylesFromString(
'<div class="ui-1ut9bc3"></div>',
styles
);
// A CSS string generated from the cache
console.log(css);
// ".ui-1ut9bc3{display:flex;}"
// A list of all of the names that were in the cache
console.log(names);
// ["1ut9bc3"]
export function createStylesFromString(
html: string,
styles = require("@dash-ui/styles").styles
): ServerStylesResult;
| Argument | Type | Required? | Default | Description |
|---|---|---|---|---|
| html | string | Yes | An HTML string | |
| styles | styles | No | styles | A styles instance |
export interface ServerStylesResult {
/**
* A CSS string containing all of the styles that were used
*/
css: string;
/**
* Hash names of all of the styles used in the generated CSS
*/
names: string[];
}
Creates a <style> tag w/ CSS based on an HTML string. This function will parse your HTML
output for Dash class names and pull the styles associated with them from the Dash cache.
This is a safe way to generate <style> tags in an asynchronous environment.
import { styles } from "@dash-ui/styles";
import { createStyleTagFromString } from "@dash-ui/styles/server";
// Inserts a new class for `display: flex;`
styles.cls`display: flex;`;
// This function will match names in the style cache against
// class names found in your HTML string. It will create a <style>
// tag from the names it finds.
const styleTag = createStyleTagFromString(
'<div class="ui-1ut9bc3"></div>',
styles
);
console.log(styleTag);
// "<style data-dash=\"1ut9bc3\" data-cache=\"ui\">.ui-1ut9bc3{display:flex;}</style>"
function createStyleTagFromString(
html: string,
styles = require("@dash-ui/styles").styles
): string;
| Argument | Type | Required? | Default | Description |
|---|---|---|---|---|
| html | string | Yes | An HTML string | |
| styles | styles | No | styles | A styles instance |
string; // A <style> tag with css generated from the cache
Writes a CSS to a file based on an HTML string. This function will parse your HTML output for Dash class names and pull the styles associated with them from the Dash cache.
This is a safe way to generate CSS files in an asynchronous environment.
import { styles } from "@dash-ui/styles";
import { writeStylesFromString } from "@dash-ui/styles/server";
// Inserts a new class for `display: flex;`
styles.cls`display: flex;`;
// This function will match names in the style cache against
// class names found in your HTML string. It will create a CSS
// file from the names it finds.
writeStylesFromString(
'<div class="ui-1ut9bc3"></div>',
"../public/css",
styles
).then(({ filename, css, names }) => {
// The filename where the file was written
console.log(filename);
// "../public/css/ui-115aj09.css"
// A CSS string generated from the cache
console.log(css);
// ".ui-1ut9bc3{display:flex;}"
// A list of all of the names that were in the cache
console.log(names);
// ["1ut9bc3"]
});
async function writeStylesFromString(
html: string,
outputPath = "",
styles = require("@dash-ui/styles").styles,
options?: WriteServerStylesOptions
): Promise<WriteServerStylesResult>;
| Argument | Type | Required? | Default | Description |
|---|---|---|---|---|
| html | string | Yes | An HTML string | |
| outputPath | string | No | "" | An absolute or relative path dictating where you want to output the CSS file. |
| styles | styles | No | styles | A styles instance |
| options | WriteServerStylesOptions | No | Configuration options |
export interface WriteServerStylesResult {
/**
* The filename of the generated file. This is the `outputPath` joined
* to the basename of the CSS file that was generated.
*/
filename: string;
/**
* The basename of the CSS file that was generated.
*/
name: string;
/**
* The output path of the CSS file excluding the basename.
*/
path: string;
/**
* The CSS string that was generated and written to the output
* file.
*/
css: string;
/**
* The hash names of all of the styles that were inserted into
* the generated CSS string.
*/
names: string[];
}
You can strongly type your design tokens a couple of ways. The easiest way is to create your
own styles instance with createStyles():
Play with this example on CodeSandbox
import { createStyles } from "@dash-ui/styles";
export const styles = createStyles({
// createStyles() uses these tokens to create a generic
// for variable usage in the styles instance
tokens: {
color: {
// var(--color-red)
red: "#c17",
},
},
});
styles.one(({ color }) => ({
// Will autocomplete and pass type checking
color: color.red,
// bgRed is not in our `tokens` and this will fail
// type checking
backgroundColor: color.bgRed,
}));
You can also strongly type your design tokens using a module declaration:
Play with this example on CodeSandbox
const tokens = {
color: {
red: "#c17",
},
};
type AppTokens = typeof tokens;
declare module "@dash-ui/styles" {
export interface DashTokens extends AppTokens {}
}
// OR alternatively
declare module "@dash-ui/styles" {
export interface DashTokens {
color: {
red: string;
};
}
}
You can strongly type your CSS variable themes a couple of ways. The easiest way is to create your
own styles instance with createStyles():
Play with the example on CodeSandbox
import { createStyles } from "@dash-ui/styles";
export const styles = createStyles({
// createStyles() uses these themes to create a generic
// for variable and theme usage in the styles instance
themes: {
light: {
color: {
// var(--color-bg)
bg: "#fafafa",
},
},
dark: {
color: {
// var(--color-bg)
bg: "#1a1a1a",
},
},
},
});
styles.one(({ color }) => ({
// Will autocomplete and pass type checking
backgroundColor: color.bg,
// "red" is not in our `themes` and this will fail
// type checking
color: color.red,
}));
// Likewise, this will pass typechecking
styles.theme("dark");
// This will not
styles.theme("whoami");
You can also strongly type your CSS variable themes using a module declaration:
Play with the example on CodeSandbox
const themes = {
light: {
color: {
// var(--color-bg)
bg: "#fafafa",
},
},
dark: {
color: {
// var(--color-bg)
bg: "#1a1a1a",
},
},
};
type AppThemes = typeof themes;
type AppTokens = AppThemes["dark"] & AppThemes["light"];
declare module "@dash-ui/styles" {
export interface DashTokens extends AppTokens {}
export interface DashThemes extends AppThemes {}
}
// OR alternatively
declare module "@dash-ui/styles" {
export interface DashTokens {
color: {
bg: string;
};
}
export interface DashThemes {
light: DashTokens;
dark: DashTokens;
}
}
This library was heavily inspired by the original Emotion and fellow Coloradan Kye Hohenberger.
I am grateful to have had that base, however, the implementations of the libraries have diverged quite a bit by now.
MIT
FAQs
A tiny, powerful, framework-agnostic CSS-in-JS library.
The npm package @dash-ui/styles receives a total of 450 weekly downloads. As such, @dash-ui/styles popularity was classified as not popular.
We found that @dash-ui/styles 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
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.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.