Brandeur NPM | npm.io

Brandeur

Brandeur is a convenience layer and tool belt on top of css-hooks for React.

Support Us

Support Robin Weser's work on Brandeur and its ecosystem directly via GitHub Sponsors.

Benefits

Same API
Vendor Prefixing
Fallback Value Support
Keyframes Support
Fela Plugin Compatibility

The Gist

import { createHooks } from 'brandeur'
import prefixer, { fallbacks } from 'brandeur-plugin-prefixer'

const theme = {
  colors: { primary: 'red' },
}

const [staticCSS, css] = createHooks({
  hooks: {
    // either custom hooks or @css-hooks/recommended
  },
  plugins: [prefixer()],
  fallbacks: [
    ...fallbacks,
    { property: 'position', values: ['-webkit-sticky', 'sticky'] },
  ],
  keyframes: {
    fadeIn: {
      from: { opacity: 0 },
      to: { opacity: 1 },
    },
  },
  theme,
})

// fades in, red color, vendor prefixed and browser-compatible position: sticky
const style = css(({ theme, keyframes }) => ({
  animationName: keyframes.fadeIn,
  color: theme.colors.primary,
  position: 'sticky',
  appearance: 'none',
}))

Why

tbd.

API

Currently Brandeur only exposes two functions:

createHooks

The main API that wraps createHooks from css-hooks. It returns the same structural array including both the static CSS and the css function. The difference is that the static CSS includes more than just the hooks and the css function also accepts functions.

Arguments

It accepts the following arguments as an object.

Argument	Type	Description
plugins	Array\	List of plugins that are used to process each style before transforming into a flat hooks style. See Plugins for a list of all available plugins.
fallbacks	Array\	List of fallbacks that are added and automatically replace within style objects.
keyframes	Object	A map of animationName-keyframe pairs.
theme	Object	A theme object that can be accessed from within style functions.

Plugin

type Plugin = style => style

Plugins are simple functions that take a style object and return a new one, similar to Fela plugins.

Note: See Plugins for a list of all available plugins.

Fallback

type Fallback = {
  property: string | Array<string>
  values: Array<string>
  match?: string
}

Tip: The fallbackValue API provides a convenient way to create those fallback objects.

Returns

It returns an array where the first item is a static CSS string and the second item is the css function to create styles. The css function accepts both style object as well as functions where the first argument is an object that only has a theme property.

Example

See The Gist.

fallbackValue

A tiny helper function to create fallbacks in a more convenient way.

Arguments

It accepts the following arguments as an object.

Argument	Type	Description
property	Array\ \| string	A property or list of properties for which the fallback value applies.
values	Array\	A list of fallback values where the last one is the default.
match	string?	An optional matcher string that's used to replace values in style objects. Defaults to the last `values` value.

Returns

(Fallback) An object with respective fallback properties.

Example

import { fallbackValue } from 'brandeur'

const positionSticky = fallbackValue('position', ['-webkit-sticky', 'sticky'])

Plugins

The following table shows all plugins available for Brandeur. It supports quite a bunch of Fela plugins, but might not always be fully compatible. Therefore we're highlighting the differences as well.

Name	Description	Compatibility
brandeur-plugin-enforce-longhands	Specific implementation of sort-properties. Enforces longhand over shorthand properties for more deterministic results.	-
brandeur-plugin-prefixer	Adds vendor prefixes to style objects.	-
brandeur-plugin-sort-properties	Sorts properties according to a priorty map. Helpful when trying to enforce certain properties over others.	-
brandeur-plugin-responsive-values	Resolves responsive array values.	-
fela-plugin-bidi	Enables direction-independent styles by converting them to either `rtl` or `ltr` on the fly.	Does not support context-specific `direction` via `theme`.
fela-plugin-custom-property	Resolves custom properties.	Full
fela-plugin-expand-shorthand	Expands shorthand properties into their longhand forms.	Full
fela-plugin-extend	Adds a convenient syntax for (conditionally) extending styles.	Full
fela-plugin-hover-media	Wraps `:hover` styles in `@media (hover: hover)` queries.	Full
fela-plugin-kebab-case	Converts properties written in kebab-case to camelCase.	Full
fela-plugin-logger	Logs processed style objects.	Full
fela-plugin-multiple-selectors	Resolves multiple comma-separated selectors to individual object keys.	Full
fela-plugin-responsive-value	Resolves array values to pre-defined media queries. Useful for component APIs.	Does not support the `props` argument to receive the `theme`. Use a static `theme` instead.
fela-plugin-rtl	Converts styles to their right-to-left counterpart	Does not support context-specific `direction` via `theme`.
fela-plugin-unit	Automatically adds units to values if needed.	Full
fela-plugin-validator	Validates, logs & optionally deletes invalid properties for keyframes and rules.	Full

Incompatible Fela Plugins

Plugin	Alternative
fela-plugin-prefixer	Use brandeur-plugin-prefixer instead.
fela-plugin-named-keysfela-plugin-friendly-pseudo-classfela-plugin-pseudo-prefixerfela-plugin-fullscreen-prefixerfela-plugin-placeholder-prefixer	Use `hooks` directly to set those.
fela-plugin-embedded	No replacement yet due to missing font and keyframe primitives.
fela-plugin-theme-value	No replacement yet due to incompatible plugin APIs.