A Style Thing
Style aware components on top of Better Style Sheets.
npm i stylething
Stylething is a css-in-js utility for creating React Javascript components that have styles attached to them. Stylething works in tandem with the BSS library and is inspired by styled-components and @emotion/styled.
As with styled-components and @emotion/styled, Stylething allows users to combine visual primitives into component systems by just defining component styles.
Unlike styled-components and emotion, Stylething is geared to also work well with virtual DOM libraries other than React.
Table of Contents
Usage
Installation
Sylething was designed to work in concert with BSS (css-in-js-layer) and a virtual DOM library of your choosing (currently adapters exist for React, Preact and Mithril). Install BSS, Stylething and e. g. Mithril via npm
:
npm i mithril bss stylething
Setup
First, import the Vdom library and BSS.
Then create a styled
component factory.
// Set up styled component factoryconst styled = // create a componentconst PlainButton =
Stylething ships without dependencies. Hence passing the BSS
and Mithril
instance into createComponentFactory
is required to instrument the styled
function.
Style aware components
With PlainButton
we now have a style aware Mithril component.
Style aware means that the component recognises any css style attribute passed as a prop.
// rendering PlainButton with ad hoc style overridesm
A live example is available here.
Static defaults
Ad hoc style overrides as demonstrated above, shall come in handy when used in tandem with static style definition at component initialisation.
Static component styles may be declared by passing a style definition as the 2nd argument of the styled
factory.
// pass a fancy button style definition (example uses bss),// note bss shorthand style attributes!const FancyButton = const tealOrTomato = Math > 05 ? 'teal' : 'tomato' // rendering FancyButton, overriding just backgroundColorm
A live example is available here.
The Stylething API is flexible. Any of the following static style definition flavours (or combinations thereof) are supported:
1) BSS style definition (recommended)
BSS is the recommended way for defining styles. Refer to the BSS documentation for more details.
const Box =
2) Hyperscript queries
const Span = // <span id="identifyer" class="one two" hot=true hyper="cool"></span>
3) Externally defined css classes
It is possible to reference external css by passing a class string as the second argument
const Box = // <div class="externally defined class"></div>
4) POJO style definition
const Box =
Inherit and extend
It is possible to extend the static style definition of a previously defined component by passing said component into the styled
factory as the first argument.
// The Button from the last section without the interpolationsconst StandardButton = // A new component based on StandardButton, but with some override stylesconst TomatoButton =
Stylething supports the "as" polymorphic prop. This allows users to dynamically swap out the element that will receive the styles down the line.
m
A live example is available here
Responsive Styles and Theming
For handling responsive styles, it is recommended to define media queries directly on the BSS instance.
// use BSS media query groupersbb // set up styled component factoryconst styled = // create a responsively styled static componentconst Responsive = m
A live example is available here
Preconfigured media querie groupers for BSS are available in the stylething/bssHelpers
module. The following examples illustrates how to activate Stylething helpers:
// initialising Stylething helpers on the BSS instanceb
Initialize Stylething helpers by passing the return value of the createBssHelpers
function into the helper
method of the b
instance.
[TODO] link to list of available helpers
CSS systems
The styled
component factory was designed to also work in tandem with style yielding functions provided by libraries such as Systemthing and styled-system. This represents an alternative (albeit slightly more expensive) approach to working with themed values and responsive styles.
Tapping style yielding functions is useful in situations where responsive ad hoc style overwrites can not be avoided.
Style yielding functions are available via npm
.
npm i systemthing
The styled
component factory can then be overloaded with n-number of these functions.
// create a dynamic responsively styled componentconst Responsive = m
A live example is available here.
Custom theme
Systemthing's default values can be customised when initially setting up the styled
factory. Here is an idiomatic example that passes a custom theme into Stylethings createComponentFactory
function.
const newTheme = breakpoints: '32em' '48em' '64em' space: 0 6 12 18 24 fontSizes: 12 16 18 24 36 72 radii: 3 5 7 colors: blue: '#07c' green: '#1c0' gray: '#ccc' '#555' // aliasesnewThemespacebig = 64newThemefontSizesbig = 128 const styled = const Button = m
Live example is availabe here
An example theme with preset values can be obtained from the the stylething/theme
module.
The default theme exposes the following values
/* lib/theme.js */ // docs/style-cookbook/media-queries.mdconst breakpoints = '30em' '60em' // docs/style-cookbook/layout/spacing.mdconst space = 0 '.25rem' '.5rem' '1rem' '2rem' '4rem' '8rem' '16rem' // docs/style-cookbook/typography/type-scale.mdconst fontSizes = '.75rem' '.875rem' '1rem' '1.25rem' '1.5rem' '2.25rem' '3rem' '5rem' '6rem' fontSizessubheadline = fontSizes 7 fontSizesheadline = fontSizes 8 // docs/style-cookbook/themed/border-radii.mdconst radii = '0' '.125rem' '.25rem' '.5rem' '1rem' radiipill = '9999px'radiimax = '100%' // docs/style-cookbook/themed/colors.mdconst colors = // Grayscale Solids black: '#000' nearBlack: '#111' darkGray: '#333' midGray: '#555' gray: '#777' silver: '#999' lightSilver: '#aaa' moonGray: '#ccc' lightGray: '#eee' nearWhite: '#f4f4f4' white: '#fff' // Grayscale Transparencies transparent: 'transparent' black90: 'rgba(0,0,0,.9)' black80: 'rgba(0,0,0,.8)' black70: 'rgba(0,0,0,.7)' black60: 'rgba(0,0,0,.6)' black50: 'rgba(0,0,0,.5)' black40: 'rgba(0,0,0,.4)' black30: 'rgba(0,0,0,.3)' black20: 'rgba(0,0,0,.2)' black10: 'rgba(0,0,0,.1)' black05: 'rgba(0,0,0,.05)' black025: 'rgba(0,0,0,.025)' black0125: 'rgba(0,0,0,.0125)' white90: 'rgba(255,255,255,.9)' white80: 'rgba(255,255,255,.8)' white70: 'rgba(255,255,255,.7)' white60: 'rgba(255,255,255,.6)' white50: 'rgba(255,255,255,.5)' white40: 'rgba(255,255,255,.4)' white30: 'rgba(255,255,255,.3)' white20: 'rgba(255,255,255,.2)' white10: 'rgba(255,255,255,.1)' white05: 'rgba(255,255,255,.05)' white025: 'rgba(255,255,255,.025)' white0125: 'rgba(255,255,255,.0125)' // Colors darkRed: '#e7040f' red: '#ff4136' lightRed: '#ff725c' orange: '#ff6300' gold: '#ffb700' yellow: '#ffd700' lightYellow: '#fbf1a9' purple: '#5e2ca5' lightPurple: '#a463f2' darkPink: '#d5008f' hotPink: '#ff41b4' pink: '#ff80cc' lightPink: '#ffa3d7' darkGreen: '#137752' green: '#19a974' lightGreen: '#9eebcf' navy: '#001b44' darkBlue: '#00449e' blue: '#357edd' lightBlue: '#96ccff' lightestBlue: '#cdecff' washedBlue: '#f6fffe' washedGreen: '#e8fdf5' washedYellow: '#fffceb' washedRed: '#ffdfdf'
Documentation
- todo