brandeur
v0.0.8
Published
Convenience layer and tool belt for css-hooks
Downloads
218
Maintainers
Readme
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<Plugin> | 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<Fallback> | 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> | string | A property or list of properties for which the fallback value applies. |
| values | Array<string> | 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. |
Roadmap
- TypeScript Support
- RTL Conversion
- Theming Primitives
- Configuration
- Framework-Agnostic API
License
Brandeur is licensed under the MIT License. Documentation is licensed under Creative Commons License. Created with ♥ by @robinweser.