boxoid
v0.2.0
Published
A tool for prefilling React component props, as well as a styling utility.
Downloads
14
Maintainers
Readme
boxoid
boxoid is a tool for prefilling React component props, as well as a styling utility. It's tiny and has no external dependencies. It has a single export. When combined with a className generation function, it's actually more flexible than classical styled functions.
import box from 'boxoid'
import { css } from '@emotion/css'
export const Button = box('button', {
className: css({ background: 'red' }),
})
// use it inside React as:
return <Button />
// Adding a further className is possible. Both classes will be combined.
return <Button className="extra-class"/>
It has a first-class TypeScript support. Prefilling turns required props into optional props.
import box from 'boxoid'
export const OutlinedButton = box(Button, {
variant: 'outlined',
})
The second argument can also be a function that takes props, and returns the props to be prefilled.
import box from 'boxoid'
export const OutlinedButton = box('button', (props: { isDisabled?: boolean }) => ({
disabled: props.isDisabled,
}))
There's no need for using some shouldForwardProp
mechanism to avoid passing isDisabled
down. Destructed props are automatically marked as non-passdown props thanks to ES6 Proxy.
Mutliple style variants is a great example that demonstrates the advantages of boxoid over classical styled functions.
import box from 'boxoid'
import cx from 'classnames'
import { css } from '@emotion/css'
const classes = {
root: css({ ... }),
...
}
export const Button = box(
'button',
(props: { variant?: 'default' | 'danger'; disabled?: boolean }) => ({
classNames: cx([
classes.root,
classes.variant[props.variant || 'default'],
{ [classes.disabled]: props.disabled },
]),
disabled: props.disabled,
})
)
In classical styled, multiple variants like above are:
- Less developer-friendly as they force the developer to a "ternary operator hell"
- Less performant as they conduct their own className generation internally, and this requires deep-comparisons of CSS objects in every render.
A criticism against Material-UI styled API
In MUI v4, different flavors of styled is exported, as its defaut form is not enough. There are MUI components that receive multiple classes using the classes
prop. For one-off styling, the classes
prop can be used, however for reusing styles, there's an additional styled flavor called withStyles
.
With boxoid, there's no need for any additional API to learn. box
+ css
combination is sufficient.
const StyledComponent = box(MuiComponent, {
classes: {
root: classes.root,
paper: classes.paper,
}
})
You can think of boxoid as a meta-styled function.
// A reductionist interpretation
const styled = (as, styles) => box(as, { className: css(styles) })
You can also use hooks inside the box
function!
import { useAtom } from '@xoid/react'
import type { Atom } from 'xoid'
const Input = box('input', (props: { atom: Atom<string> }) => {
value: useAtom(props.atom),
onChange: (e) => props.atom.set(e.target.value)
})
xoid is a framework-agnostic state management library by me. It aims to unify the API for local state, global state, and finite state machines. See its website!
Extension
Perhaps you want to add a cx
prop that uses your favorite classnames library internally:
import _box, { Box } from 'boxoid'
import cx, { ClassValue } from 'clsx'
const cxPlugin = (
left: { cx?: ClassValue; className?: string },
right: { cx?: ClassValue; className?: string }
) => {
const { cx: cx1, className: cn1 } = left;
const { cx: cx2, className: cn2 } = right;
delete left.cx;
delete right.cx;
if (cx1 || cn1 || cx2 || cn2) right.className = cx(cx1, cn1, cx2, cn2);
};
export const box: Box<{ cx?: ClassValue }> = _box.bind(cxPlugin)
Plugins receive shallow copies of the following objects. It's safe to manipulate these objects in a mutable way.
const Div = box('div', () => %left%)
const Div = box('div', %left%)
React.createElement(Div, %right%)