📦 ui-box is a low level CSS-in-JS solution that focuses on being simple, fast and extensible. All CSS properties are set using simple React props, which allows you to easily create reusable components that can be enhanced with additional CSS properties. This is very useful for adding things like margins to components, which would normally require adding non-reusable wrapper elements/classes.
yarn add ui-box
# or
npm install --save ui-boximport Box from 'ui-box'
function Button(props) {
return (
<Box
is="button"
padding="10px"
background="red"
{...props}
/>
)
}
function Example() {
return <Button disabled margin="10px">Hi</Button>
}The above example component renders a red, disabled <button> with margins.
Type: string or React component type
Default: 'div'
Lets you change the underlying element type. You can pass either a string to change the DOM element type, or a React component type to inherit another component. The component just needs to accept a className prop to work. A good example is inheriting the react-router Link component.
E.g:
<Box is={Link} to="/login">Login</Box>Type: function
Callback that gets passed a ref to inner DOM node (or component if the is prop is set to a React component type).
Type: boolean
Utility property for easily adding clearfix styles to the element.
Type: string
The className prop you know and love. Internally it gets enhanced with additional class names for the CSS properties you specify.
All of these CSS properties are support. You can pass either a string or a number (which gets converted to a px value). The shorthand properties with repeated values only accept a single value, e.g. margin="10px" works but margin="10px 20px" does not. You can use the x/y props (e.g. marginX/marginY) to achieve the same thing.
alignContentalignItemsalignSelfbackgroundbackgroundBlendModebackgroundClipbackgroundColorbackgroundImagebackgroundOriginbackgroundPositionbackgroundRepeatbackgroundSizeborderborderBottomborderBottomColorborderBottomLeftRadiusborderBottomRightRadiusborderBottomStyleborderBottomWidthborderColorborderLeftborderLeftColorborderLeftStyleborderLeftWidthborderRadiusborderRightborderRightColorborderRightStyleborderRightWidthborderStyleborderTopborderTopColorborderTopLeftRadiusborderTopRightRadiusborderTopStyleborderTopWidthborderWidthbottomboxShadowboxSizing- Set toborder-boxby default.clearcolorcolumnGapcursordisplayflexflexBasisflexDirectionflexFlowflexGrowflexShrinkflexWrapfloatfontfontFamilyfontSizefontStylefontVariantfontWeightgapgridgridAreagridAutoColumnsgridAutoFlowgridAutoRowsgridColumngridColumnEndgridColumnGapgridColumnStartgridGapgridRowgridRowEndgridRowGapgridRowStartgridTemplategridTemplateAreasgridTemplateColumnsgridTemplateRowsheightjustifyContentjustifyItemsjustifySelfleftletterSpacinglineHeightlistStylelistStyleImagelistStylePositionlistStyleTypemarginmarginBottommarginLeftmarginRightmarginTopmarginX- SetsmarginLeftandmarginRightto the same value.marginY- SetsmarginTopandmarginBottomto the same value.maxHeightmaxWidthminHeightminWidthopacityorderoverflowoverflowXoverflowYpaddingpaddingBottompaddingLeftpaddingRightpaddingToppaddingX- SetspaddingLeftandpaddingRightto the same value.paddingY- SetspaddingTopandpaddingBottomto the same value.placeContentplaceItemsplaceSelfpointerEventspositionrightrowGaptextAligntextDecorationtextOverflowtextShadowtextTransformtoptransformtransformOrigintransitiontransitionDelaytransitionDurationtransitionPropertytransitionTimingFunctionuserSelectvisibilitywhiteSpacewidthwordBreakwordWrapzIndex
All other props passed through to the underlying DOM element / React component.
Returns a { cache, styles } object which contains the cache entries and rendered styles for server rendering. The styles can be output in a <style> tag or an external stylesheet (however you want). The cache should be passed to hydrate() on the client-side before mounting the app. Also useful for doing snapshot unit testing (make sure to call clearStyles() after each test though).
Hydrates the cache using the cache value returned from extractStyles(). This is used to prevent needing to recalculate all the class names and re-render all the styles on page load when server rendering.
Clears the cache and removes the rendered styles. Mainly useful for resetting the global state when using extractStyles() in unit tests.
Utility function for filtering out props based on an array of keys. Returns an { matchedProps, remainingProps } object.
Type: object
Type: array[string]
Utility function for filtering out Box props. Returns an { matchedProps, remainingProps } object.
Type: object
Object of all the Box CSS property propTypes.
Array of all the Box CSS property names.
Array of the Box CSS property aliases (the shorthand properties).
Object of all the CSS property enhancers (the methods that generate the class name and styles for each property).
These enhancer groups are also exported. They're all objects with { propTypes, propAliases, propEnhancers } properties. They're mainly useful for if you want to inherit a subset of the Box CSS propTypes in your own components.
backgroundborderRadiusbordersboxShadowdimensionsflexinteractionlayoutlistopacityoverflowpositionspacingtexttransformtransition
To render the styles on the server side just use ReactDOMServer.renderToString() as usual and then call the extractStyles() method retrieve the rendered styles and cache. The styles can then be output to a <style> tag or an external stylesheet. The cache data should be passed to the hydrate() method on the client side before you call ReactDOM.hydrate().
For example:
'use strict'
const React = require('react')
const ReactDOMServer = require('react-dom/server')
const {default: Box, extractStyles} = require('.')
const element = React.createElement(Box, {margin: '10px', color: 'red'}, 'hi')
const html = ReactDOMServer.renderToString(element)
const {styles, cache} = extractStyles()
const page = `
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Page</title>
<style>
${styles}
</style>
</head>
<body>
<main id="root">
${html}
</main>
<script type="application/json" id="ui-box-cache">
${JSON.stringify(cache)}
</script>
</body>
</html>
`
console.log(page)yarn devstarts the development Storybook at http://localhost:9009/.yarn testruns the linter, unit tests and code coverage.yarn ava -wruns the unit tests in watch mode.yarn ava -uupdates the snapshot tests.yarn buildtranspiles the JavaScript files.yarn releasereleases a new version (requiresnpto be installed globally).
ui-box is released under the MIT license.
Copyright © 2017 Segment.io, Inc.