Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/prometheusresearch-archive/react-stylesheet

Component based styling for your React applications
https://github.com/prometheusresearch-archive/react-stylesheet

css-in-js react react-components

Last synced: 7 days ago
JSON representation

Component based styling for your React applications

Awesome Lists containing this project

README 

        
# React Stylesheet



[![Build Status](https://img.shields.io/travis/prometheusresearch/react-stylesheet.svg)](https://travis-ci.org/prometheusresearch/react-stylesheet)

[![NPM Version](https://img.shields.io/npm/v/react-stylesheet.svg)](https://npmjs.org/packages/react-stylesheet)



Component based styling approach for React applications.



**Table of Contents**



- [Motivation](#motivation)

- [Installation](#installation)

- [Usage](#usage)

  - [``](#element-)

    - [Styling based on state (hover, focus, ...)](#styling-based-on-state-hover-focus-)

    - [Overriding component](#overriding-component)

  - [`` and ``](#vbox--and-hbox-)

  - [Styled component factories](#styled-component-factories)

    - [Styling based on state (hover, focus, ...)](#styling-based-on-state-hover-focus--1)

    - [Variants](#variants)

    - [Type safety](#type-safety)

  - [CSS helpers](#css-helpers)

  - [Test utilities](#test-utilities)



## Motivation



This library implements a components-based approach for styling React

applications. Stying with components means styling with JS code.



To re-iterate on CSS-in-JS advantages:



* Single language to define UI and to style it—JavaScript.



* Existing tooling for JavaScript can be reused for stylesheets: linters, type

  checkers, formatters, ...



* A lot of features CSS is missing are present in JavaScript: modules,

  functions, variables, ...



For more info on CSS-in-JS and its advantages see [the excellent

talk][css-in-js] by Vjeux.



What makes React Stylesheet special:



* React centric approach: there's no separate abstractions for styles, React

  Stylesheet produces React components directly. You don't need to pass

  `className` or `style` props around. The units of reusability are React

  components.



* Type safety: React Stylesheet is fully typesafe. That can help you catch typos

  and invalid style values.



* React Stylesheet compiles to CSS classes under the hood: that means `hover`,

  `focus` states are supported.



[css-in-js]: http://blog.vjeux.com/2014/javascript/react-css-in-js-nationjs.html



## Installation



```

% npm install react-stylesheet

```



## Usage



### ``



`` component is a basic building block for styling:



```

import {Element} from 'react-stylesheet'



  I'm styled!



```



#### Styling based on state (hover, focus, ...)



For each prop like `color`, `background`, ... there are versions with suffixes

`*OnHover`, `*onActive`, `*onActive`, and `*onDisabled` which activate its style

values when the corresponding state is being active.



For example there's an `` which changes its background and text color

on hover:



```

import {Element} from 'react-stylesheet'



  I'm styled!



```



#### Overriding component



By default `` renders into `
` DOM component but you can

override this with `Component` prop:



```



  click me!



```



It can be a composite component but the requirement is that it takes `style` and

`className` props.



### `` and ``



`` and `` are thin wrappers on top of `` which

implement [flexbox][] layout mechanism.



`` corresponds to a flex container with `flex-direction: column` and

`` — `flex-direction: row`.



All properties which are supported by `` are also supported by ``

and ``.



```

import {VBox, HBox} from 'react-stylesheet'



  Block 1

  Block 2



```



Note that the following defaults are applied:



```

HBox, VBox {

  position: relative;



  overflow: hidden;



  margin: 0;

  padding: 0;



  display: flex;

  align-items: stretch;

  flex-basis: auto;

  flex-shrink: 0;



  min-height: 0;

  min-width: 0;

}

```



[flexbox]: https://css-tricks.com/snippets/css/a-guide-to-flexbox/



### Styled component factories



There's a way to produce styled components out of common components using

`style(Component, stylesheet)` function:



```

import {style} from 'react-stylesheet'



let Label = style('span', {

  base: {

    fontWeight: 'bold',

    fontSize: '12pt',

  }

})

```



Now `Label` is a regular React component styled with `fontWeight` and

`fontSize`. You can render into DOM and use as a part of React element tree:



```



```



#### Styling based on state (hover, focus, ...)



You can specify styling for states (hover, focus, ...):



```

let Label = style('span', {

  base: {

    fontWeight: 'bold',

    fontSize: '12pt',

    hover: {

      textDecoration: 'underline'

    }

  }

})

```



Now on hover you can see the underline appears.



#### Variants



Sometimes you want a set of style variants and toggle them via JS:



```

let Label = style('span', {

  base: {

    fontWeight: 'bold',

    fontSize: '12pt',

  },

  emphasis: {

    textDecoration: 'underline'

  },

})

```



Now to toggle any particular variant you need to pass a component a specially

constructed `variant` prop:



```



```



#### Type safety



React DOM Stylesheet comes with Flow typings which precisely describe available

API.



Some examples of the type errors you can get:



```

style('span', {

  display: 'oops' // display can only be "none" | "block" | ...

})



style('span', {

  isplay: 'block' // unknown property "isplay"

})

```



### CSS helpers



There's helpers for producing CSS values:



```

import {css} from 'react-stylesheet'



let Label = style('span', {

  base: {

    border: css.border(1, css.rgb(167)),

  }

})

```



### Test utilities



React Stylesheet comes with snapshot serializers for [Jest][] test framework.



The example test setup looks like this:



    import React from 'react';

    import renderer from 'react-test-renderer';



    import {Element} from 'react-stylesheet';

    import * as TestUtils from 'react-stylesheet/testutils';



    expect.addSnapshotSerializer(TestUtils.snapshotSerializer);



    function Hello() {

      return HEllo!

    }



    test('rendering ', function() {

      const tree = renderer.create().toJSON();

      expect(tree).toMatchSnapshot();

    });



Which produces the following snapshot:



    


      Hello

    



Alternatively if you don't want to call `expect.addSnapshotSerializer(..)` line

in each of your test files you can the following config to your `package.json`:



    "jest": {

      "snapshotSerializers": ["react-stylesheet/testutils-snapshot-serializer"]

    }



This will enable snapshot serializers for each of your test files.



[Jest]: https://facebook.github.io/jest/