Griffel for React
Install
npm install @griffel/react
yarn add @griffel/react
API
makeStyles()
Is used to define styles, returns a React hook that should be called inside a component:
import { makeStyles } from '@griffel/react';
const useClasses = makeStyles({
button: { color: 'red' },
icon: { paddingLeft: '5px' },
});
function Component() {
const classes = useClasses();
return (
<div>
<button className={classes.button} />
<span className={classes.icon} />
</div>
);
}
mergeClasses()
💡 It is not possible to simply concatenate classes returned by useClasses()
.
There are cases where you need to merge classes from multiple useClasses
calls.
To properly merge the classes, you need to use mergeClasses()
function, which performs merge and deduplication of atomic classes generated by makeStyles()
.
import { mergeClasses, makeStyles } from '@griffel/react';
const useClasses = makeStyles({
blueBold: {
color: 'blue',
fontWeight: 'bold',
},
red: {
color: 'red',
},
});
function Component() {
const classes = useClasses();
const firstClassName = mergeClasses(classes.blueBold, classes.red);
const secondClassName = mergeClasses(classes.red, classes.blueBold);
return (
<>
<div className={firstClassName} />
<div className={secondClassName} />
</>
);
}
shorthands
shorthands
provides a set of functions to mimic CSS shorthands and improve developer experience as CSS shorthands are not supported by Griffel.
shorthands.border
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.border('2px'),
...shorthands.border('2px', 'solid'),
...shorthands.border('2px', 'solid', 'red'),
},
});
shorthands.borderBottom
, shorthands.borderTop
, shorthands.borderLeft
, shorthands.borderRight
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.borderBottom('2px'),
...shorthands.borderBottom('2px', 'solid'),
...shorthands.borderBottom('2px', 'solid', 'red'),
},
});
shorthands.borderColor
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.borderColor('red'),
...shorthands.borderColor('red', 'blue'),
...shorthands.borderColor('red', 'blue', 'green'),
...shorthands.borderColor('red', 'blue', 'green', 'yellow'),
},
});
shorthands.borderStyle
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.borderStyle('solid'),
...shorthands.borderStyle('solid', 'dashed'),
...shorthands.borderStyle('solid', 'dashed', 'dotted'),
...shorthands.borderStyle('solid', 'dashed', 'dotted', 'double'),
},
});
shorthands.borderWidth
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.borderWidth('12px'),
...shorthands.borderWidth('12px', '24px'),
...shorthands.borderWidth('12px', '24px', '36px'),
...shorthands.borderWidth('12px', '24px', '36px', '48px'),
},
});
shorthands.gap
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.gap('12px'),
...shorthands.gap('12px', '24px'),
},
});
shorthands.margin
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.margin('12px'),
...shorthands.margin('12px', '24px'),
...shorthands.margin('12px', '24px', '36px'),
...shorthands.margin('12px', '24px', '36px', '48px'),
},
});
shorthands.overflow
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.overflow('visible'),
...shorthands.overflow('visible', 'hidden'),
},
});
shorthands.padding
import { makeStyles, shorthands } from '@griffel/react';
const useClasses = makeStyles({
root: {
...shorthands.padding('12px'),
...shorthands.padding('12px', '24px'),
...shorthands.padding('12px', '24px', '36px'),
...shorthands.padding('12px', '24px', '36px', '48px'),
},
});
makeStaticStyles()
Creates styles attached to a global selector. Styles can be defined via objects:
import { makeStaticStyles } from '@griffel/react';
const useStaticStyles = makeStaticStyles({
'@font-face': {
fontFamily: 'Open Sans',
src: `url("/fonts/OpenSans-Regular-webfont.woff2") format("woff2"),
url("/fonts/OpenSans-Regular-webfont.woff") format("woff")`,
},
body: {
background: 'red',
},
});
function App() {
useStaticStyles();
return <div />;
}
Or with string & arrays of strings/objects:
import { makeStaticStyles } from '@griffel/react';
const useStaticStyles1 = makeStaticStyles('body { background: red; } .foo { color: green; }');
const useStaticStyles2 = makeStaticStyles([
{
'@font-face': {
fontFamily: 'My Font',
src: `url(my_font.woff)`,
},
},
'html { line-height: 20px; }',
]);
function App() {
useStaticStyles1();
useStaticStyles2();
return <div />;
}
createDOMRenderer()
, RendererProvider
createDOMRenderer
is paired with RendererProvider
component and is useful for child window rendering and SSR scenarios. This is the default renderer for web, and will make sure that styles are injected to a document.
import { createDOMRenderer, RendererProvider } from '@griffel/react';
function App(props) {
const { targetDocument } = props;
const renderer = React.useMemo(() => createDOMRenderer(targetDocument), [targetDocument]);
return (
<RendererProvider renderer={renderer} targetDocument={targetDocument}>
{/* Children components */}
{/* ... */}
</RendererProvider>
);
}
styleElementAttributes
A map of attributes that's passed to the generated style elements. For example, is useful to set "nonce" attribute.
import { createDOMRenderer } from '@griffel/react';
const renderer = createDOMRenderer(targetDocument, {
styleElementAttributes: {
nonce: 'random',
},
});
Features support
📃 pseudo & class selectors, at-rules, global styles
makeStyles()
supports pseudo, class selectors and at-rules.
import { makeStyles } from '@griffel/react';
const useClasses = makeStyles({
root: {
':active': { color: 'pink' },
':hover': { color: 'blue' },
'.foo': { color: 'black' },
':nth-child(2n)': { backgroundColor: '#fafafa' },
'@media screen and (max-width: 992px)': { color: 'orange' },
'@supports (display: grid)': { color: 'red' },
'@layer utility': { marginBottom: '1em' }
},
});
Another useful feature is :global()
selector, it allows connecting local styles with global selectors.
import { makeStyles } from '@griffel/react';
const useClasses = makeStyles({
root: {
':global(html[data-whatintent="mouse"])': { backgroundColor: 'yellow' },
},
});
🎞 keyframes
(animations)
keyframes
are supported via animationName
property that can be defined as an object or an array of objects:
import { makeStyles } from '@griffel/react';
const useClasses = makeStyles({
root: {
animationIterationCount: 'infinite',
animationDuration: '3s',
animationName: {
from: { transform: 'rotate(0deg)' },
to: { transform: 'rotate(360deg)' },
},
},
array: {
animationIterationCount: 'infinite',
animationDuration: '3s',
animationName: [
{
from: { transform: 'rotate(0deg)' },
to: { transform: 'rotate(360deg)' },
},
{
from: { height: '100px' },
to: { height: '200px' },
},
],
},
});
CSS Fallback Properties
Any CSS property accepts an array of values which are all added to the styles.
Every browser will use the latest valid value (which might be a different one in different browsers, based on supported CSS in that browser):
import { makeStyles } from '@griffel/react';
const useClasses = makeStyles({
root: {
overflowY: ['scroll', 'overlay'],
},
});