DOCSEARCHbyAlgolia
Submit Docs

goober

website·Indexed 30 days ago

https://goober.js.org/

A css-in-js solution under 1KB. It provides a lightweight way to style components using tagged template literals, featuring a `styled` API, `css` function, and `createGlobalStyles`. It includes support for TypeScript, autoprefixing, and integrations for Gatsby, Preact CLI, and Babel via plugins and macros.

Tokens
4.5K
Snippets
36
Records
41
Agent score
66%

What's inside goober

  1. Overview of goober CSS-in-JS features

    goober provides a comprehensive set of CSS-in-JS capabilities including basic CSS parsing, support for nested rules with pseudo-selectors, and media queries (@media) and keyframes (@keyframes). It supports smart (lazy) client-side hydration and allows for the extraction of styles from elements other than the <head>. It also includes built-in vendor prefixing.

  2. Filter props passed to DOM elements using shouldForwardProp

    Use the goober/should-forward-prop addon within the setup function to define which props should be forwarded to the DOM. This allows you to prevent custom styling props (e.g., those starting with a specific symbol) from appearing in the final HTML output without manually looping over all props.
    import { h } from 'preact';
import { setup } from 'goober';
import { shouldForwardProp } from 'goober/should-forward-prop';

setup(
  h,
  undefined,
  undefined,
  shouldForwardProp((prop) => {
    // Do NOT forward props that start with the `$` symbol
    return prop[0] !== '$';
  })
);

  3. Enable the custom css prop using the goober Babel plugin

    To use a custom css prop for passing styles directly to HTML elements in goober, you must install and configure the @agney/babel-plugin-goober-css-prop Babel plugin.
    npm install --save-dev @agney/babel-plugin-goober-css-prop
    // .babelrc
{
  "plugins": [
    "@agney/babel-plugin-goober-css-prop"
  ]
}

  4. Use the should-forward-prop addon for simplified prop filtering

    Instead of manually mutating the props object in setup(), you can use the goober/should-forward-prop addon. This provides a wrapper that accepts a filter function; if the filter returns false, the prop is excluded from the DOM.
    import React from 'react';
import { setup } from 'goober';
import { shouldForwardProp } from 'goober/should-forward-prop';

setup(
  React.createElement,
  undefined,
  undefined,
  shouldForwardProp((prop) => {
    return prop !== 'size';
  })
);

  5. Configure a custom CSS prefixer in goober

    You can provide a custom prefixer function as the second argument to setup(). This function is responsible for formatting the CSS key-value pairs.
    import React from 'react';
import { setup } from 'goober';

const customPrefixer = (key, value) => `${key}: ${value};\n`;

setup(React.createElement, customPrefixer);

  6. Extend styles by wrapping a styled component

    To share or overwrite styles from an existing styled component, pass the original component as the argument to the styled function. The new component will inherit the styles of the original and apply the additional CSS rules provided.
    import { styled } from "goober";

// Define a base primitive component
const Primitive = styled("span")`
  margin: 0;
  padding: 0;
`;

// Extend the primitive with additional styles
const Container = styled(Primitive)`
  padding: 1em;
`;

  7. Filter props forwarded to the DOM using forwardProps

    The fourth argument of setup() is the forwardProps function. This function receives the entire props object, allowing you to delete specific props (such as theme variables or custom variants) so they do not end up as attributes in the final DOM element.
    import React from 'react';
import { setup } from 'goober';

setup(React.createElement, undefined, undefined, (props) => {
  for (let prop in props) {
    if (prop === 'size') {
      delete props[prop];
    }
  }
});

  8. Enable CSS autoprefixing in goober

    To ensure generated CSS works across a wide spectrum of browsers, goober provides an optional autoprefixer package. You must install the core package and then pass the prefix function from goober/prefixer into the setup function during initialization.
    npm install goober
# or
yarn add goober
    import { setup } from 'goober';
import { prefix } from 'goober/prefixer';

// Bootstrap goober with the prefixer
setup(React.createElement, prefix);

  9. Enable styled.tag syntax using babel-plugin-transform-goober

    The babel-plugin-transform-goober plugin allows developers to use the styled.tag syntax (e.g., styled.div) by automatically translating it into goober's standard styled("tag") function calls during the build process.
    # Install via npm
npm i --save-dev babel-plugin-transform-goober

# Or install via yarn
yarn add --dev babel-plugin-transform-goober

  10. Define reusable style functions for dynamic class names

    To avoid re-declaring styles inside a render loop or to manage timing, wrap the css call in a function.

    • Direct call: Executed when the file is imported.
    • Wrapped function: Executed when the function is called (typically during render).

    Note: If using extractCSS for Server-Side Rendering (SSR), wrapping css in a function or using the styled API is recommended to avoid inconsistent results.

    import { css } from "goober";

const BtnClassName = (props) => css`
  border-radius: ${props.size}px;
`;

// vanilla JS
const btn = document.querySelector("#btn");
btn.classList.add(BtnClassName({ size: 20 }));

// JSX
const App = () => <button className={BtnClassName({ size: 20 })}>click</button>;

  11. Initialize goober with a pragma function

    The setup() function must be called exactly once in the project's entry file to initialize goober. It requires a pragma function (like React.createElement for React or h for Preact) to handle transformed elements, which helps reduce bundle size and supports ES modules.
    import React from 'react';
import { setup } from 'goober';

setup(React.createElement);

  12. Extract critical CSS for SSR

    To implement Server-Side Rendering (SSR) with goober, use the extractCss function to retrieve the critical CSS generated during the render process.