π₯ goober, a less than 1KB css-in-js solution.
Motivation
I always wondered, if you can get a working solution for css-in-js with a smaller footprint. I started a project and wanted a to use styled-components. Looking at their sizes, it seems that I would rather not include ~12kB(styled-components) or ~11kB(emotion) just so I can use the styled
paradigm. So, I embarked in a mission to create a smaller alternative for these well established apis.
Table of contents
Usage
The API is inspired by emotion, styled
function. Meaning, you call it with your tagName
and returns a vDOM component for that tag. Note, setup
is needed to be run before the styled
function is used.
import { h } from 'preact';
import { styled, setup } from 'goober';
// Should be called here, and just once
setup(h);
const Icon = styled('span')`
display: flex;
flex: 1;
color: red;
`;
const Button = styled('button')`
background: dodgerblue;
color: white;
border: ${Math.random()}px solid white;
&:focus,
&:hover {
padding: 1em;
}
.otherClass {
margin: 0;
}
${Icon} {
color: black;
}
`;
Examples
SSR
You can get the critical CSS for SSR, via extractCss
. Take a look at this example: CodeSandbox: SSR with Preact and goober and read the full explanation for extractCSS
and targets
below.
Benchmarks
You results are included inside the build output as well.
Browser
These are not yet measured. Need some time.
SSR
The benchmark is testing the following scenario:
import styled from 'package';
// Create the dynamic styled component
const Foo = styled('div')((props) => ({
opacity: props.counter > 0.5 ? 1 : 0,
'@media (min-width: 1px)': {
rule: 'all'
},
'&:hover': {
another: 1,
display: 'space'
}
}));
// Serialize the component
renderToString(<Foo counter={Math.random()} />);
The results are:
goober x 39,348 ops/sec Β±1.67% (87 runs sampled)
styled-components x 21,469 ops/sec Β±3.60% (85 runs sampled)
emotion x 46,504 ops/sec Β±4.67% (85 runs sampled)
Fastest is: emotion
API
As you can see it supports most of the syntaxes of CSS. If you find any issues, please submit a ticket or even a PR with a fix.
styled(tagName: String | Function, forwardRef?: Function)
@param {String|Function} tagName
The name of the dom element you'd like the styled to be applied to@param {Function} forwardRef
Forward ref function. UsuallyReact.forwardRef
@returns {Function}
Returns the tag template function.
import { styled } from 'goober';
const Btn = styled('button')`
border-radius: 4px;
`;
Different ways of customizing the styles
Tagged templates functions
import { styled } from 'goober';
const Btn = styled('button')`
border-radius: ${(props) => props.size}px;
`;
<Btn size={20} />;
Function that returns a string
import { styled } from 'goober';
const Btn = styled('button')(
(props) => `
border-radius: ${props.size}px;
`
);
<Btn size={20} />;
JSON/Object
import { styled } from 'goober';
const Btn = styled('button')((props) => ({
borderRadius: props.size + 'px'
}));
<Btn size={20} />;
Arrays
import { styled } from 'goober';
const Btn = styled('button')([
{ color: 'tomato' },
({ isPrimary }) => ({ background: isPrimary ? 'cyan' : 'gray' })
]);
<Btn />; // This will render the `Button` with `background: gray;`
<Btn isPrimary />; // This will render the `Button` with `background: cyan;`
setup(pragma: Function, prefixer?: Function, theme?: Function)
Given the fact that react
uses createElement
for the transformed elements and preact
uses h
, setup
should be called with the proper pragma function. This was added to reduce the bundled size and being able to bundle esmodule version. At the moment I think it's the best tradeoff we can have.
import React from 'react';
import { setup } from 'goober';
setup(React.createElement);
With prefixer
import React from 'react';
import { setup } from 'goober';
const customPrefixer = (key, value) => `${key}: ${value};\n`;
setup(React.createElement, customPrefixer);
With theme
import React from 'react';
import { setup, styled } from 'goober';
const theme = { primary: 'blue' };
const ThemeContext = createContext(theme);
const useTheme = () => useContext(ThemeContext);
setup(React.createElement, undefined, useTheme);
const ContainerWithTheme = styled('div')`
color: ${(props) => props.theme.primary};
`;
css(taggedTemplate)
@returns {String}
Returns the className.
To create a className, you need to call css
with your style rules in a tagged template.
import { css } from "goober";
const BtnClassName = css`
border-radius: 4px;
`;
// vanilla JS
const btn = document.querySelector("#btn");
// BtnClassName === 'g016232'
btn.classList.add(BtnClassName);
// JSX
// BtnClassName === 'g016232'
const App => <button className={BtnClassName}>click</button>
css
Different ways of customizing css
tagged templates
Passing props to import { css } from 'goober';
// JSX
const CustomButton = (props) => (
<button
className={css`
border-radius: ${props.size}px;
`}
>
click
</button>
);
css
with JSON/Object
Using import { css } from 'goober';
const BtnClassName = (props) =>
css({
background: props.color,
borderRadius: props.radius + 'px'
});
Notice: using css
with object can reduce your bundle size.
We also can declare the styles at the top of the file by wrapping css
into a function that we call to get the className.
import { css } from 'goober';
const BtnClassName = (props) => css`
border-radius: ${props.size}px;
`;
// vanilla JS
// BtnClassName({size:20}) -> g016360
const btn = document.querySelector('#btn');
btn.classList.add(BtnClassName({ size: 20 }));
// JSX
// BtnClassName({size:20}) -> g016360
const App = () => <button className={BtnClassName({ size: 20 })}>click</button>;
The difference between calling css
directly and wrapping into a function is the timing of its execution. The former is when the component(file) is imported, the latter is when it is actually rendered.
If you use extractCSS
for SSR, you may prefer to use the latter or styled
api to avoid inconsistent results.
targets
By default, goober will append a style tag to the <head>
of a document. You might want to target a different node, for instance, when you want to use goober with web components (so you'd want it to append style tags to individual shadowRoots). For this purpose, you can .bind
a new target to the styled
and css
methods:
import * as goober from 'goober';
const target = document.getElementById('target');
const css = goober.css.bind({ target: target });
const styled = goober.styled.bind({ target: target });
If you don't provide a target, goober always defaults to <head>
and in environments without a DOM (think certain SSR solutions), it will just use a plain string cache to store generated styles which you can extract with extractCSS
(see below).
extractCss(target?)
@returns {String}
Returns the <style>
tag that is rendered in a target and clears the style sheet. Defaults to <head>
.
const { extractCss } = require('goober');
// After your app has rendered, just call it:
const styleTag = `<style id="_goober">${extractCss()}</style>`;
// Note: To be able to `hydrate` the styles you should use the proper `id` so `goober` can pick it up and use it as the target from now on
glob
To create a global style, you need to call glob
with your global tagged template. Usually here's a good idea to place document wide styles.
import { glob } from 'goober';
glob`
html,
body {
background: light;
}
* {
box-sizing: border-box;
}
`;
keyframes
keyframes
is a helpful method to define reusable animations that can be decoupled from the main style declaration and shared across components.
import { keyframes } from 'goober';
const rotate = keyframes`
from, to {
transform: rotate(0deg);
}
50% {
transform: rotate(180deg);
}
`;
const Wicked = styled('div')`
background: tomato;
color: white;
animation: ${rotate} 1s ease-in-out;
`;
Integrations
Babel plugin
You're in love with the styled.div
syntax? Fear no more! We got you covered with a babel plugin that will take your lovely syntax from styled.tag
and translate it to goober's styled("tag")
call.
npm i --save-dev babel-plugin-transform-goober
# or
yarn add --dev babel-plugin-transform-goober
Visit the package in here for more info (https://github.com/cristianbote/goober/tree/master/packages/babel-plugin-transform-goober)
Gatsby
Want to use goober
with Gatsby? We've got you covered! We have our own plugin to deal with styling your Gatsby projects.
npm i --save gatsby-plugin-goober
# or
yarn add gatsby-plugin-goober
Features
- Basic CSS parsing
- Nested rules with pseudo selectors
- Nested styled components
- Extending Styles
- Media queries (@media)
- Keyframes (@keyframes)
- Smart(lazy) client-side hydration
- Styling any component
- via
const Btn = ({className}) => {...}; const TomatoBtn = styled(Btn)`color: tomato;`
- via
- Vanilla(via
css
function) -
globalStyle
(viaglob
) so one would be able to create global styles - target/extract from elements other than
<head>
- vendor prefixing
Sharing style
There are a couple of ways to effectly share/extend styles across components.
Extending
One can simply extend the desired component that needs to be enrich or overwriten with another set of css rules.
import { styled } from 'goober';
// Let's declare a primitive for our styled component
const Primitive = styled('span')`
margin: 0;
padding: 0;
`;
// Later on we could get the primitive shared styles and also add our owns
const Container = styled(Primitive)`
padding: 1em;
`;
as
prop
Using Another helpful way to extend a certain component is with the as
property. Given our example above we could modify it like:
import { styled } from 'goober';
// Our primitive element
const Primitive = styled('span')`
margin: 0;
padding: 0;
`;
const Container = styled('div')`
padding: 1em;
`;
// At composition/render time
<Primitive as={'div'} /> // <div class="go01234" />
// Or using the `Container`
<Primitive as={Container} /> // <div class="go01234 go56789" />
Autoprefixer
Autoprefixing is a helpful way to make sure the generated css will work seamlessly on the whole spectrum of browsers. With that in mind, the core goober
package can't hold that logic to determine the autoprefixing needs, so we added a new package that you can choose to address them.
npm install goober-autoprefixer
# or
yarn add goober-autoprefixer
After the above package is installed it's time to bootstrap goober with it:
import { setup } from 'goober';
import { prefix } from 'goober-autoprefixer';
// Bootstrap goober
setup(React.createElement, prefix);
And voila! It is done!
Browser support
goober
uses microbundle to bundle and transpile it's src into code that browsers can leverage. As you might figure it out, until now, Internet Explorer was the buggiest of them all. goober
works on IE9, as we've successfully test it.
IE 9
iOS 9.3
Chrome 42
FF 34
Safari 9
Contributing
Feel free to try it out and checkout the examples. If you wanna fix something feel free to open a issue or a PR.
Backers
Thank you to all our backers! π
Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website.