@dash-ui/react
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    React components and hooks for dash-ui
    npm i @dash-ui/react
    Bundlephobia Types Code coverage Build status NPM Version MIT License

    Quick Start

    NOTE: You do not need to use this package to use @dash-ui with React. This merely provides a few useful utilities, particularly on the server-side.

    Check out an example on CodeSandbox

    import { createStyles } from "@dash-ui/styles";
    import { useGlobal } from "@dash-ui/react";
    
    const styles = createStyles({
      tokens: {
        color: {
          primary: "#ee5b5f",
        },
      },
    });
    
    const Heading = () => {
      useGlobal(
        styles,
        ({ color }) => `
          h1 {
            font-size: 2rem;
            font-family: -apple-system, sans-serif;
            color: ${color.primary};
          }
        `,
        []
      );
    
      return <h1>Hello world</h1>;
    };

    API docs

    Components

    Component Description
    <Inline> A component for creating an inline <style> tag that is unmounted when the component unmounts.

    Hooks

    Hook Description
    useCSS() A hook for performantly and reliably inserting CSS into the DOM in React 18 using the useInsertionEffect hook.
    useGlobal() A hook for inserting transient global styles into the DOM. These styles will be injected when the hook mounts and flushed when the hook unmounts.
    useTokens() A hook for inserting transient CSS tokens into the DOM. These tokens will be injected when the hook mounts and flushed when the hook unmounts.
    useThemes() A hook for inserting transient CSS theme tokens into the DOM. These tokens will be injected when the hook mounts and flushed when the hook unmounts.

    Server rendering

    Description
    <Style> A React component for injecting SSR CSS styles into Next.js documents.
    toComponent() A function for creating a React <style> component for inserting Dash styles in SSR.
    createGatsbyRenderer Creates a Gatsby replaceRenderer for injecting styles generated by Dash on the server into the Gatsby <head> component

    TypeScript support

    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 CSS tokens.
    Strongly typed themes Learn how to add autocomplete and type safety to your CSS variable themes.

    <Inline>

    A component for creating an inline <style> tag that is unmounted when the component unmounts.

    Example

    Play with an example on CodeSandbox

    import * as React from 'react'
    import {styles} from '@dash-ui/styles'
    import {Inline} from '@dash-ui/react'
    
    export const App = () => {
      return (
        <React.Fragment>
          <Inline styles={styles} css={`
            .heading {
              font-size: 2rem;
              font-family: -apple-system, sans-serif;
            }
          `}>
          <h1 className='heading'>Hello world</h1>
        </React.Fragment>
      )
    }

    Props

    Prop Type Required? Description
    styles Styles<DashTokens, DashThemes> Yes A styles instance.
    css StyleValue<DashTokens> Yes The CSS you want to inline in the DOM.

    useCSS()

    A hook for performantly and reliably inserting CSS into the DOM in React 18 using the useInsertionEffect hook.

    Example

    Play with an example on CodeSandbox

    import * as React from "react";
    import { createStyles } from "@dash-ui/styles";
    import { useGlobal } from "@dash-ui/react";
    
    const styles = createStyles();
    
    const Component = () => {
      const classes = useCSS(styles, {
        root: styles.one({ display: "flex", gap: "2rem" }),
      });
    
      return (
        <div className={classes.root}>
          <div>Hello</div>
          <div>World</div>
        </div>
      );
    };

    Returns

    Record<ClassNames, string>;

    useGlobal()

    A hook for inserting transient global styles into the DOM. These styles will be injected when the hook mounts and flushed when the hook unmounts.

    Example

    Play with an example on CodeSandbox

    import * as React from "react";
    import { createStyles } from "@dash-ui/styles";
    import { useGlobal } from "@dash-ui/react";
    
    const styles = createStyles();
    
    const Component = () => {
      useGlobal(
        styles,
        {
          body: {
            minHeight: "100vh",
            backgroundColor: "#ee5b5f",
            color: "#fff",
            fontFamily: "Inter, -apple-system, sans-serif",
          },
          h1: {
            margin: "1rem",
            fontSize: "3rem",
          },
        },
        []
      );
    
      return (
        <div>
          <h1>Hello world</h1>
        </div>
      );
    };

    Returns

    null;

    useTokens()

    A hook for inserting transient CSS tokens into the DOM. These tokens will be injected when the hook mounts and flushed when the hook unmounts.

    Example

    Play with an example on CodeSandbox

    import * as React from "react";
    import { createStyles } from "@dash-ui/styles";
    import { useThemes } from "@dash-ui/react";
    
    const styles = createStyles({
      tokens: {
        primaryColor: "#ee5b5f",
      },
    });
    
    const Component = () => {
      const [primaryColor, setPrimaryColor] = React.useState("#ee5b5f");
    
      useTokens(styles, { 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>
      );
    };

    Arguments

    function useTokens(
      value: PartialDeep<DashTokens> | Falsy,
      deps?: React.DependencyList
    );

    | Argument | Type | Required? | Description | | -------- | -------------------------------- | --------- | --------------------------------------------------------------- | ------------------------------------------------------------------ | | styles | Styles<DashTokens, DashThemes> | Yes | A styles instance. | | value | PartialDeep<DashTokens> | Falsy | Yes | CSS tokens to inject into the DOM and flush when the hook unmounts | | deps | React.DependencyList | No | A dependency array that will force the hook to re-insert tokens |

    Returns

    null;

    useThemes()

    A hook for inserting transient CSS theme tokens into the DOM. These tokens will be injected when the hook mounts and flushed when the hook unmounts.

    Example

    Play with an example on CodeSandbox

    import * as React from "react";
    import { createStyles } from "@dash-ui/styles";
    import { useThemes } from "@dash-ui/react";
    
    const styles = createStyles({
      themes: {
        // Light mode CSS tokens
        light: {
          primaryColor: "#ee5b5f",
        },
        // Dark mode CSS tokens
        dark: {
          primaryColor: "#272727",
        },
      },
    });
    
    const Component = () => {
      const [mode, setMode] = React.useState("light");
      const [darkModePrimary, setDarkModePrimary] = React.useState("#272727");
      const [lightModePrimary, setLightModePrimary] = React.useState("#ee5b5f");
    
      useThemes(
        {
          light: {
            primaryColor: lightModePrimary,
          },
          dark: {
            primaryColor: darkModePrimary,
          },
        },
        [darkModePrimary, lightModePrimary]
      );
    
      return (
        <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>
      );
    };

    Arguments

    function useThemes(
      styles,
      value: PartialDeep<DashThemes> | Falsy,
      deps?: React.DependencyList
    );
    Argument Type Required? Description
    styles Styles<DashTokens, DashThemes> Yes A styles instance.
    value PartialDeep<DashThemes>| Falsy Yes Themes to inject into the DOM and flush when the hook unmounts
    deps React.DependencyList No A dependency array that will force the hook to re-insert themes

    Returns

    null;

    <Style>

    A React component for injecting SSR CSS styles into Next.js documents.

    Example

    // _document.js
    import React from "react";
    import Document from "next/document";
    import { styles } from "@dash-ui/styles";
    import { Style } from "@dash-ui/react/server";
    
    export default class MyDocument extends Document {
      static async getInitialProps(ctx) {
        const initialProps = await Document.getInitialProps(ctx);
    
        return {
          ...initialProps,
          styles: (
            <React.Fragment>
              {initialProps.styles}
              <Style html={initialProps.html} styles={styles} />
            </React.Fragment>
          ),
        };
      }
    }

    Props

    Prop Type Required? Description
    html string Yes HTML generated by Next.js, renderToStaticMarkup() or renderToString()
    styles Styles<DashTokens, DashThemes> No An instance of styles. Defaults to the default styles instance in @dash-ui/styles.

    toComponent()

    A function for creating a React <style> component for inserting Dash styles in SSR.

    Example

    // _document.js
    import React from "react";
    import Document from "next/document";
    import { styles } from "@dash-ui/styles";
    import { toComponent } from "@dash-ui/react/server";
    
    export default class MyDocument extends Document {
      static async getInitialProps(ctx) {
        const initialProps = await Document.getInitialProps(ctx);
    
        return {
          ...initialProps,
          styles: (
            <React.Fragment>
              {initialProps.styles}
              {toComponent(initialProps.html, styles)}
            </React.Fragment>
          ),
        };
      }
    }

    Arguments

    function toComponent(
      html: string,
      styles: Styles = defaultStyles
    ): React.ReactElement;
    Argument Type Required? Description
    html string Yes The HTML generated by renderToStaticMarkup() or renderToString()
    styles Styles<DashTokens, DashThemes> No An instance of styles. Defaults to the default styles instance in @dash-ui/styles.

    Returns

    React.ReactElement; // A <style> element

    createGatsbyRenderer()

    Creates a Gatsby replaceRenderer for injecting styles generated by Dash on the server into the Gatsby <head> component.

    Example

    // gatsby-ssr.js
    const { styles } = require("@dash-ui/styles");
    
    exports.replaceRenderer =
      require("@dash-ui/react/server").createGatsbyRenderer(styles);

    Arguments

    function createGatsbyRenderer(styles: Styles = defaultStyles);
    Argument Type Required? Description
    styles Styles<DashTokens, DashThemes> Yes An instance of styles. Defaults to the default styles instance in @dash-ui/styles.

    Returns

    function replaceRenderer<P = any>(props: P): P; // A Gatsby replace renderer

    Strongly typed tokens

    To use variable types with @dash-ui/react, you have to use the module declaration pattern:

    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;
        };
      }
    }

    Strongly typed themes

    To use variable/theme types with @dash-ui/react, you have to use the module declaration pattern:

    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;
      }
    }

    LICENSE

    MIT

    Install

    npm i @dash-ui/react

    DownloadsWeekly Downloads

    134

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    137 kB

    Total Files

    29

    Last publish

    Collaborators

    • jaredlunde