README.md

🎩 Stylish | Preact

Stylish is a tiny yet capable CSS library for Preact apps. It is heavily inspired by @emotion/styled and styled-components, so if you are familiar with either of those, you should quickly get the hang of Stylish.

Features

• Extremely lightweight (under 1KB gzipped)
• No dependencies (uses the Preact/HTM you already have)
• Comprehensive test suite (100% code coverage)
• Animations supported
• Theme context provided right out of the box
• CSS rules have access to component props
• Auto-generated class names (never have to use a className or style prop again!)
• Make any component stylish
• No React shims needed -- built for Preact

Installing

npm install stylish-preact

Yarn users, you know what to do instead.

Usage

Learn Stylish by example. The following examples use htm instead of JSX, so they will run directly in a modern web browser, no transpilation needed.

Basic Example

import { html } from 'htm/preact';
import { render } from 'preact';
import { stylish } from 'stylish-preact';

const RedText = stylish('div', `
  color: red;
`);

render(html`
  <${RedText}>Hi, I'm red!<//>
`, document.body);

Example with props

import { html } from 'htm/preact';
import { render } from 'preact';
import { stylish } from 'stylish-preact';

const Tint = stylish('div', (props) => `
  color: ${props.color};
`);

render(html`
  <${Tint} color="blue">Hi, I'm blue!<//>
`, document.body);

Example with pseudo-classes

import { html } from 'htm/preact';
import { render } from 'preact';
import { stylish } from 'stylish-preact';

const HoverGreen = stylish('div', {
  rule: `
    color: green;
  `,
  states: [':hover']
});

render(html`
  <${HoverGreen}>Hi, hover me to make me green!<//>
`, document.body);

Example with animation

import { keyframes, stylish } from 'stylish-preact';

import { html } from 'htm/preact';
import { render } from 'preact';

const spin = keyframes`
  from {
    transform: rotate(0deg);
  }

  to {
    transform: rotate(360deg);
  }
`;

const Spinner = stylish('div', `
  animation: 1s infinite linear ${spin};
`);

render(html`
  <${Spinner}>Weeeeee!<//>
`, document.body);

Example with inheritance

import { html } from 'htm/preact';
import { render } from 'preact';
import { stylish } from 'stylish-preact';

const Big = stylish('span', `
  font-size: 4em;
`);

const BigAndBlue = stylish(Big, `
  color: blue;
`);

render(html`
  <${BigAndBlue}>Hi, I'm big and blue.<//>
`, document.body);

Example with theme

import { Theme, stylish } from 'stylish-preact';

import { html } from 'htm/preact';
import { render } from 'preact';

const Logo = stylish('h1', ({ theme }) => `
  color: ${theme.color.primary};
`);

render(html`
  <${Theme.Provider} value=${{ color: { primary: 'purple' }}}>
    <${Logo}>Purple Power<//>
  <//>
`, document.body);

Migrating from @emotion/styled or styled-components?

There are some notable differences between Stylish and these two libraries.

• Stylish does not support nested rules. It is primitive in that way. Each set of properties must be defined in its own rule, complete with any media selector and/or states (pseudo-classes or other criteria) applicable to that rule.

• The stylish function behaves differently than the styled function for either of these two libraries. Read through the examples and usage documentation prior to reporting issues. Most notably, stylish should not be used as a tagged template.

API Reference

import { Theme } from 'stylish-preact';

Theme is a context. To provide a theme, <Theme.Provider value={theme}>...<//>. This theme will be automatically injected to all stylish components. To access the theme directly, const theme = useContext(Theme);, just like you would any other context.

The shape of the theme you define is completely up to you. Stylish does not use it directly; it only passes it through, if present, so your stylish components have access to it without having to do any additional work.

import { keyframes } from 'stylish-preact';

The keyframes function can be used as a tagged template or invoked directly. Use it to define an animation. It returns the animation's name which can then be injected into other components to use that animation.

import { stylish } from 'stylish-preact';

The stylish function creates a stylish component. It takes two arguments:

stylish(Component, ...)

The first argument may be the string name of the HTML element to serve as the component's base element.

Alternatively, the first argument may be a reference to another component to extend. For example, const Convertible = stylish(Vehicle);.

stylish(..., outfit)

The second argument is where the whole outfit comes together. It can be a string, a function, an object, or an array of strings/functions/objects. These all define aspects of how the stylish component is dressed.

String

When outfit is a string, it should contain a set of static CSS properties describing the component's appearance.

Function

Whe outfit is a function, it should expect to be given the props given to the component when it is rendered, and should return a string containing the set of CSS properties describing the component's appearance.

Object

When outfit is an object, it should contain the following properties:

• rule - Required. This should be either a string or a function which behaves as described above.

• media - Optional. If present, this should be a media selector string. For example, (max-width: 500px).

• states - Optional. If present, this should be string[], where each item is a suffix to be added to the component's CSS selector for this rule block. For example, a simple :hover or a more complex :not(:last-of-type)::after.

Array

When outfit is an array, each item in the array should conform to the above requirements depending on the type of that item (string vs function vs object).