1 | # Rendition
|
2 |
|
3 | [![npm version](https://badge.fury.io/js/rendition.svg)](http://badge.fury.io/js/rendition)
|
4 | [![Dependency Status](https://img.shields.io/david/balena-io-modules/rendition.svg)](https://david-dm.org/balena-io-modules/rendition)
|
5 | [![style: styled-components](https://img.shields.io/badge/style-%F0%9F%92%85%20styled--components-orange.svg?colorB=daa357&colorA=db748e)](https://github.com/styled-components/styled-components)
|
6 |
|
7 | A library of UI components, built using [React][react], [recompose][recompose], [styled-components][styled-components] and [styled-system][styled-system].
|
8 |
|
9 | ## Table of Contents
|
10 |
|
11 | * [Installation](#installation)
|
12 | * [Usage](#usage)
|
13 | * [Components](#components)
|
14 | * [Development](#development)
|
15 | * [Testing](#testing)
|
16 | * [Upgrading](#testing)
|
17 |
|
18 | ## Installation
|
19 |
|
20 | ```
|
21 | npm install --save rendition
|
22 | ```
|
23 |
|
24 | ## Usage
|
25 |
|
26 | Wrap your application in the `Provider` component and start using components!
|
27 |
|
28 | ```jsx
|
29 | import React from 'react'
|
30 | import ReactDOM from 'react-dom'
|
31 | import { Button, Box, Provider } from 'rendition';
|
32 |
|
33 | ReactDOM.render(
|
34 | <Provider>
|
35 | <Box my={3} mx={['auto', 15]}>
|
36 | <Button primary emphasized>Click me</Button>
|
37 | </Box>
|
38 | </Provider>,
|
39 | document.getElementById('root')
|
40 | );
|
41 | ```
|
42 |
|
43 | ## Components
|
44 |
|
45 | For an interactive demo of all components, see https://balena-io-modules.github.io/rendition
|
46 |
|
47 | {% COMPONENT_DOCS %}
|
48 |
|
49 | ### Provider
|
50 |
|
51 | Wrap your application in the `<Provider>` component so that child components can correctly inherit the default theme. You can optionally provide your own theme.
|
52 |
|
53 | ### Accessing the theme object
|
54 |
|
55 | You can access the theme object in `<Provider>`'s descendant components using the `useTheme` hook:
|
56 |
|
57 | ```jsx
|
58 | import React from 'react'
|
59 | import { useTheme } from 'rendition';
|
60 |
|
61 | const MyComponent = () => {
|
62 | const theme = useTheme()
|
63 |
|
64 | // ...
|
65 | }
|
66 | ```
|
67 |
|
68 | ### Styled system
|
69 |
|
70 | All components support [styled-system][styled-system] attributes, allowing you to use a shorthand properties for styling components. The properties can have the properties in the form of `string | number | Array<string | number>`. If an array is provided, then a property is chosen based on the width of the screen. The screen width corresponds to a breakpoint set in the `theme` property of the `Provider` component, by default this is set to `[32, 48, 64, 80]` where each number is the screen width in ems.
|
71 |
|
72 | | Name | Type | Description |
|
73 | | --------------|-------------------|--------------------------------------------- |
|
74 | | width | `ResponsiveStyle` | sets the width
|
75 | | minWidth | `ResponsiveStyle` | sets the min-width
|
76 | | maxWidth | `ResponsiveStyle` | sets the max-width
|
77 | | height | `ResponsiveStyle` | sets the height
|
78 | | minHeight | `ResponsiveStyle` | sets the min-height
|
79 | | maxHeight | `ResponsiveStyle` | sets the max-height
|
80 | | fontSize | `ResponsiveStyle` | sets the font size
|
81 | | display | `ResponsiveStyle` | sets the `display` css property
|
82 | | color | `ResponsiveStyle` | sets the `color` css property
|
83 | | bg | `ResponsiveStyle` | sets the `background` css property
|
84 | | m | `ResponsiveStyle` | sets the `margin` css property
|
85 | | mt | `ResponsiveStyle` | sets the `margin-top` css property
|
86 | | mr | `ResponsiveStyle` | sets the `margin-right` css property
|
87 | | mb | `ResponsiveStyle` | sets the `margin-bottom` css property
|
88 | | ml | `ResponsiveStyle` | sets the `margin-bottom` css property
|
89 | | mx | `ResponsiveStyle` | sets both the `margin-right` and `margin-left` css properties
|
90 | | my | `ResponsiveStyle` | sets both the `margin-top` and `margin-bottom` css properties
|
91 | | p | `ResponsiveStyle` | sets the `padding` css property
|
92 | | pt | `ResponsiveStyle` | sets the `padding-top` css property
|
93 | | pr | `ResponsiveStyle` | sets the `padding-right` css property
|
94 | | pb | `ResponsiveStyle` | sets the `padding-bottom` css property
|
95 | | pl | `ResponsiveStyle` | sets the `padding-left` css property
|
96 | | px | `ResponsiveStyle` | sets both the `padding-right` and `padding-left` css properties
|
97 | | py | `ResponsiveStyle` | sets both the `padding-top` and `padding-bottom` css properties
|
98 |
|
99 | **`ResponsiveStyle` corresponds to a type of `string | number | Array<string | number>`*
|
100 |
|
101 | ## Extra components
|
102 |
|
103 | Some components in the [storybook](https://balena-io-modules.github.io/rendition)
|
104 | are grouped separately under the `Extra` label. These components are not loaded by default
|
105 | as they rely on other large packages that you may not want to include in your
|
106 | application.
|
107 | If you would like to use them they can be loaded using by prefixing the
|
108 | component name with `rendition/dist/extra/`. For example to load the `Markdown`
|
109 | components you can use:
|
110 |
|
111 | ```
|
112 | import { Markdown } from 'rendition/dist/extra/Markdown';
|
113 | ```
|
114 |
|
115 | ## Unstable/Beta components
|
116 |
|
117 | Some components in the [storybook](https://balena-io-modules.github.io/rendition)
|
118 | are grouped seperately under the `Beta` label. These components are experimental and still
|
119 | under development, as such their API may change without notice. They should not
|
120 | be used in a production application.
|
121 | If you would like to try them out they can be loaded using
|
122 | `import * from 'rendition/dist/unstable'`.
|
123 |
|
124 | ## Upgrading
|
125 |
|
126 | [Upgrading from 3.x to 4.x](docs/migrating_3x-4x.md)
|
127 |
|
128 | [Upgrading from 4.x to 5.x](docs/migrating_4x-5x.md)
|
129 |
|
130 | [Upgrading from 6.x to 7.x](docs/migrating_6x-7x.md)
|
131 |
|
132 | ## Contributing
|
133 |
|
134 | Please read our [contribution guidelines](docs/CONTRIBUTING.md)
|
135 |
|
136 | [react]:https://reactjs.org/
|
137 | [recompose]:https://github.com/acdlite/recompose
|
138 | [styled-components]:https://www.styled-components.com/
|
139 | [styled-system]:http://jxnblk.com/styled-system/
|
140 | [husky]:https://github.com/typicode/husky
|