@impromptu/react v0.1.5

@impromptu/react

Tiny React bindings for @impromptu/css.

When minified and gzipped, this library is ~2KB.

Getting Started

import { useStylesheet } from "@impromptu/react";

export function MyComponent(): JSX.Element {
  const className = useStylesheet({
    color: "black",
    ":hover": {
      textDecoration: "underline",
    },
  });

  return <div className={className}>Hello, world!</div>;
}

API

Hooks

• useStylesheet(prefix?, ...style)
  • Appends a stylesheet to document head, for the lifetime of the component.
  • An optional namespace prefix can be given.
  • Returns the unique class name used as the stylesheet namespace.
• useMediaQuery(query)
  • Returns true if the media query matches.
  • This hook supports all CSS media queries.
• useResponsiveWidth(minWidth)
  • Returns true if the min-width is met.
  • This hook is a wrapper for useMediaQuery(``(min-width: ${minWidth}px)``).
• useTheme()
  • Returns the theme from the current context, or a default theme.
• useId(prefix?)
  • Returns a unique identifier, memoized for the lifetime of the component.
  • This hook will work even if multiple versions of this library are in use.

Components

• <Theme theme={theme}>
  • A React component which sets, overrides, or modifies the default theme.
• <Stylesheet style={style}>
  • Appends a global stylesheet to document head, for the lifetime of the component.

Utilities

• getId(prefix?)
  • Returns a unique identifier.
  • This function will work even if multiple versions of this library are in use.
• getClassName(...classNames)
  • Alias: cx(...classNames)
  • Returns a normalized class name string.
  • If a falsy value is given, it will be omitted.
  • If a map of class names is given, only those with a value of true will be included.
• getStyleText(style, namespaceSelector?)
  • Returns stylesheet text suitable for assignment to HTMLStyleElement.textContent.
• stylesheet(...style)
  • Appends a global stylesheet to document head.
  • Returns the appended <style> element.

FAQ

Q: Why not use CSS modules (e.g. babel-plugin-react-css-modules)?

CSS modules work wonderfully if you only want static styles. I you want dynamic styles which can be modified at runtime, then you want a CSS-in-JS solution. There are many scenarios where this is desirable: Animating between dynamic states, responsive design, theming, etc.

Q: Could there be memory/style leaks?

It's actually less likely in this library than in other solutions. For example, there is no caching mechanism in this library. The useStylesheet hook simply injects a <style> element when the component is mounted, and removes it when the component dismounts.

Q: Is it fast?

I haven't benchmarked it. However, efforts are made to do the least work possible, and to only update style sheets when necessary. So it should be comparable to most other solutions. The fact that this is very lightweight should also help.

Q: Why can't I use tagged templates like styled-components does?

Implementing tagged templates would significantly increase the library size, incur extra overhead at runtime for parsing (or a compilation step), and require extra IDE tooling for syntax highlighting and linting. Because size and simplicity are paramount for this library, tagged template support is not included.

Q: Should my styled components have a className property?

Probably not. Avoid using classes to change the style of a styled component. Injecting a styled class into a styled component can leading to specificity races. Well written styled components should be customizable with properties and theme values.

Q: Should my styled components have a style or styles property for injecting raw style rules?

Probably not. If the component is using dynamic styling, there's no good way for the injected styles to replicate the intended dynamic effects. If you're designing a component for reuse, give it properties and theming to support your expected level of customization.

Q: Can I extend the ThemeObject type with extra properties?

ThemeObject is an indexed type, so you can attach arbitrary values to it. The suggested pattern is to use theme values if they are defined, and to fallback to other theme values or default values for missing theme values. Remember to document the theme values that your custom component will use.

Q: How do I override the style of a styled component?

If you need to override a styled component's styles, then you need to make sure the overriding selectors have a higher specificity than the styled components styles.

Ideally, a reusable styled component should have properties and theme integration in order to support customization without having to resort to overriding the components styles with CSS.