Styles are JavaScript Objects

Can be defined inline…

import { css } from "@ptb/style"

export default () => (
  <span
    className={css({
      fontFamily: "sans-serif",
      fontSize: "24px"
    })}
  >
    Buy Now!
  </span>
)

in variables…

import { css } from "@ptb/style"

export default () => {
  const styles = {
    fontFamily: "sans-serif",
    fontSize: "24px"
  }

  return (
    <span className={css(styles)}>
      Buy Now!
    </span>
  )
}

by importing from other files…

import { css } from "@ptb/style"

export default {
  button: css({
    fontFamily: "sans-serif",
    fontSize: "24px"
  })
}

import classNames from "./styles.js"

export default () => (
  <span className={classNames.button}>
    Buy Now!
  </span>
)

…or passed as props.

import { css } from "@ptb/style"

export default ({ styles }) => (
  <span className={css(styles)}>
    Buy Now!
  </span>
)

…or an array of JavaScript Objects

import { css } from "@ptb/style"

export default () => (
  <span
    className={css([
      {
        fontFamily: "sans-serif",
        fontSize: "24px"
      },
      {
        fontSize: "36px"
      }
    ])}
  >
    Buy Now!
  </span>
)

Deep Merge Objects

If you pass an array of objects as the first argument to the css function, the objects will be expanded (as in the case of bg) then deep merged. Only the “surviving” property/value pairs are used.

Atomic Classes

Each property/value pair creates an atomic class name by default. You’ll notice that regardless of the order that the rules are listed, they always result in the same order in the stylesheet. That means that all of the textAlign properties will always be together, which makes it possible to audit the styles by just reading. This is a live editor, try changing some of the values for maxWidth or fontSize here and see what the effect is immediately. Switch to the HTML tab and notice that the class name for that property is recalculated based on the value, but the two letter prefix that is based on the property does not change.

Grouped Classes

But if you prefer to have fewer class names attached to elements, that is an option, too. Just wrap the styles in an object with as the key. Depending on your needs, you could choose to group styles together under a single class name or individual classes depending on what your needs are. If you’re planning on re-using a group of styles throughout your project, you’ll want to group them with &. It results in a slightly larger stylesheet, but fewer class names in the HTML.

Stored Variables Using $ Prefix

Shorthand Properties

Supports Styled System shorthand properties.

{
  "bg": "backgroundColor",
  "borderX": [
    "borderLeft",
    "borderRight"
  ],
  "borderY": [
    "borderBottom",
    "borderTop"
  ],
  "m": "margin",
  "mb": "marginBottom",
  "ml": "marginLeft",
  "mr": "marginRight",
  "mt": "marginTop",
  "mx": [
    "marginLeft",
    "marginRight"
  ],
  "my": [
    "marginBottom",
    "marginTop"
  ],
  "p": "padding",
  "pb": "paddingBottom",
  "pl": "paddingLeft",
  "pr": "paddingRight",
  "pt": "paddingTop",
  "px": [
    "paddingLeft",
    "paddingRight"
  ],
  "py": [
    "paddingBottom",
    "paddingTop"
  ],
  "size": [
    "height",
    "width"
  ]
}

Media Queries

Media queries can be nested or inverted. This is seriously powerful feature. If you’re creating a design to switch between light mode and dark mode, you can keep the values for each at the “bottom” of the style object under the CSS property it affects. This provides the flexibility to create a media query at any point without enforcing a specific structure.

{
  "_": "",
  "Dk": "(prefersColorScheme:dark)",
  "L": "(orientation:landscape)",
  "Lt": "(prefersColorScheme:light)",
  "Md": "(minWidth:768px)",
  "P": "(orientation:portrait)",
  "Pr": "print",
  "Prm": "(prefersReducedMotion:reduce)",
  "Prt": "(prefersReducedTransparency:reduce)",
  "R": "(WebkitMinDevicePixelRatio:2),(minResolution:192dpi)",
  "Sc": "screen",
  "Sm": "(maxWidth:767.98px)"
}

{}

@font-face Rules

@keyframes Rules

Stored Variables Using $ Prefix

$prefixes

{
  "appearance": [
    "Webkit-",
    "Moz-"
  ],
  "hyphens": [
    "Webkit-",
    "Ms-"
  ],
  "tabSize": [
    "Moz-",
    "O-"
  ],
  "userSelect": [
    "Webkit-",
    "Moz-",
    "Ms-"
  ]
}

Complex Selectors

All selectors are supported. Just be cautioned. This could be considered a bad practice. Just because you can doesn’t mean you should. You’ll notice that when global selectors are used, class names for those styles are not emitted to the element just added to the stylesheet.

Nesting Selector

Placeholder Classes (%)

Smart Integers

Converts integers to px values, except for those where it wouldn’t be correct. As examples, lineHeight, order, and fontWeight.

Fallback Array Values

Fallbacks use arrays.

Production Ready

@ptb/style is the most flexible tool kit available to style your web app. Add styles dynamically at runtime in the browser, server-side render and insert styles into the page <head>, or extract styles to a CSS file during server-side rendering or at build-time.

Single-Page or Client-Side

Without any setup, it can be used immediately to add styles and class names in any single-page application or client-side rendered app.

npm install @ptb/style

or

yarn add @ptb/style

Simply add to your project, then import it in each file where it is used. No container, context, Babel configuration, or webpack plugins required.

Server-Side Rendering

Build-Time Rendering

With Create React App

yarn create react-app my-react-app
cd my-react-app
yarn add @ptb/style
echo '' > src/styles.css

Add to src/App.js

import { css } from "@ptb/style/macro"
import "./styles.css"

Both yarn start or yarn build should work as expected, including hot reload.

yarn start
# or
yarn build

With Gatsby

Gatsby has built-in Babel macro support. No Babel setup is required.

npx gatsby new my-gatsby-app
cd my-gatsby-app
npm install @ptb/style
echo '' > src/styles.css
echo 'import "./src/styles.css"' >> gatsby-browser.js
npm run develop

To use, import the css function and use with the className prop.

import * as React from "react"
import { css } from "@ptb/style/macro"

const IndexPage = () => (
  <div
    className={css({
      alignItems: "center",
      display: "flex",
      fontSize: "64px",
      height: "100vh",
      justifyContent: "center"
    })}
  >
    Hello!
  </div>
)

export default IndexPage

Run the gatsby build command and styles will be extracted to src/styles.css and the css function call will be replaced with the associated class names.

Insert Styles Into <head>

To prevent a flash of unstyled content (FOUC), you can use the included Gatsby plugin to inline the styles in the HTML <head>. Just add the plugin to the gatsby-config.js file.

module.exports = {
  plugins: [
    {
      resolve: "@ptb/style"
    }
  ]
}

With Next.js

yarn create next-app my-next-app
cd my-next-app
yarn add @ptb/style
yarn add babel-plugin-macros
echo '' > styles/styles.css

Create (or add to) .babelrc

{
  "presets": ["next/babel"],
  "plugins": ["babel-plugin-macros"]
}

Add to package.json

  "babelMacros": {
    "@ptb/style": {
      "output": "styles/styles.css"
    }
  }

Add to pages/_app.js

import '../styles/styles.css'

Create (or add to) pages/_document.js

import { getStyles } from "@ptb/style"
import Document from "next/document"
import { Fragment } from "react"

export default class extends Document {
  static async getInitialProps(ctx) {
    const initialProps =
      await Document.getInitialProps(ctx)

    return {
      ... initialProps,
      styles: (
        <Fragment>
          {initialProps.styles}
          <style
            dangerouslySetInnerHTML={{
              __html: getStyles ()
            }}
            data-creator="@ptb/style" />
        </Fragment>
      )
    }
  }
}

In each component file, for example pages/index.js

import { css } from "@ptb/style/macro"

Start Next.js server

yarn dev

With Tailwind CSS

Using Tailwind with @ptb/style is possibly simpler than Tailwind on its own! The Babel macro twin.macro generates a JavaScript object that is perfect as input for the css function.

First, add the required packages:

yarn add babel-plugin-macros tailwindcss twin.macro

Then, in each component file, import from twin.macro and call Tailwind CSS classes as a tagged template. At build time, the tw`` expression will be replaced by a JavaScript object representing those styles.

Note: The twin.macro import must be listed before the @ptb/style/macro import.

import tw from "twin.macro"
import { css } from "@ptb/style/macro"

export default () => (
  <span
    className={css([
      tw`flex flex-col items-center justify-center h-screen`,
      {
        fontFamily: "sans-serif",
        fontSize: "24px"
      }
    ])}
  >
    Buy Now!
  </span>
)

With Vite

npm create vite@latest my-vite-app
cd my-vite-app
npm install @ptb/style
npm install vite-plugin-babel-macros
echo '' > src/styles.css
npm run dev

Add to vite.config.js

import reactPlugin from "@vitejs/plugin-react"
import { defineConfig } from "vite"
import macroPlugin from "vite-plugin-babel-macros"

export default defineConfig({
  plugins: [
    macroPlugin(),
    reactPlugin(),
  ]
})

Add to src/main.jsx

import "./styles.css"

Add to src/App.jsx

import { css } from "@ptb/style/macro"

export default function App () {
  return (
    <div
      className={css({
        alignItems: "center",
        display: "flex",
        fontSize: "64px",
        height: "100vh",
        justifyContent: "center"
       })}
    >
      Hello!
    </div>
  )
}