5 | 2 | 3 |
4 |
5 |
Make your React Components aware of their width and/or height!
6 | 7 | 8 |9 | 10 | [](http://npm.im/react-sizeme) 11 | [](http://opensource.org/licenses/MIT) 12 | [](https://travis-ci.org/ctrlplusb/react-sizeme) 13 | [](https://codecov.io/github/ctrlplusb/react-sizeme) 14 | 15 | - Hyper Responsive Components! 16 | - Performant. 17 | - Easy to use. 18 | - Extensive browser support. 19 | - Supports functional and class Component types. 20 | - Tiny bundle size. 21 | - Demo: https://4mkpc.csb.app/ 22 | 23 | Use it via the render prop pattern (supports `children` or `render` prop): 24 | 25 | ```javascript 26 | import { SizeMe } from 'react-sizeme' 27 | 28 | function MyApp() { 29 | return
46 | 47 | --- 48 | 49 | ## TOCs 50 | 51 | - [Intro](https://github.com/ctrlplusb/react-sizeme#intro) 52 | - [Installation](https://github.com/ctrlplusb/react-sizeme#installation) 53 | - [Configuration](https://github.com/ctrlplusb/react-sizeme#configuration) 54 | - [Component Usage](https://github.com/ctrlplusb/react-sizeme#component-usage) 55 | - [HOC Usage](https://github.com/ctrlplusb/react-sizeme#hoc-usage) 56 | - [`onSize` callback alternative usage](https://github.com/ctrlplusb/react-sizeme#onsize-callback-alternative-usage) 57 | - [Under the hood](https://github.com/ctrlplusb/react-sizeme#under-the-hood) 58 | - [Examples](#examples) 59 | - [Loading different child components based on size](#loading-different-child-components-based-on-size) 60 | - [Server Side Rendering](https://github.com/ctrlplusb/react-sizeme#server-side-rendering) 61 | - [Extreme Appreciation](https://github.com/ctrlplusb/react-sizeme#extreme-appreciation) 62 | - [Backers](https://github.com/ctrlplusb/react-sizeme#backers) 63 | 64 |
65 | 66 | --- 67 | 68 | ## Intro 69 | 70 | Give your Components the ability to have render logic based on their height and/or width. Responsive design on the Component level. This allows you to create highly reusable components that can adapt to wherever they are rendered. 71 | 72 | Check out a working demo here: https://4mkpc.csb.app/ 73 | 74 |
75 | 76 | --- 77 | 78 | ## Installation 79 | 80 | Firstly, ensure you have the required peer dependencies: 81 | 82 | ```bash 83 | npm install react react-dom 84 | ``` 85 | 86 | > **Note:** We require >=react@0.14.0 and >=react-dom@0.14.0 87 | 88 | ```bash 89 | npm install react-sizeme 90 | ``` 91 | 92 |
93 | 94 | --- 95 | 96 | ## Configuration 97 | 98 | The following configuration options are available. Please see the usage docs for how to pass these configuration values into either the [component](#component-usage) or [higher order function](#hoc-usage). 99 | 100 | - `monitorWidth` (_boolean_, **default**: true) 101 | 102 | If true, then any changes to your Components rendered width will cause an recalculation of the "size" prop which will then be be passed into your Component. 103 | 104 | - `monitorHeight` (_boolean_, **default**: false) 105 | 106 | If true, then any changes to your Components rendered height will cause an 107 | recalculation of the "size" prop which will then be be passed into 108 | your Component. 109 | 110 | > PLEASE NOTE: that this is set to `false` by default 111 | 112 | - `refreshRate` (_number_, **default**: 16) 113 | 114 | The maximum frequency, in milliseconds, at which size changes should be recalculated when changes in your Component's rendered size are being detected. This should not be set to lower than 16. 115 | 116 | - `refreshMode` (_string_, **default**: 'throttle') 117 | 118 | The mode in which refreshing should occur. Valid values are "debounce" and "throttle". 119 | 120 | "throttle" will eagerly measure your component and then wait for the refreshRate to pass before doing a new measurement on size changes. 121 | 122 | "debounce" will wait for a minimum of the refreshRate before it does a measurement check on your component. 123 | 124 | "debounce" can be useful in cases where your component is animated into the DOM. 125 | 126 | > NOTE: When using "debounce" mode you may want to consider disabling the placeholder as this adds an extra delay in the rendering time of your component. 127 | 128 | - `noPlaceholder` (_boolean_, **default**: false) 129 | 130 | By default we render a "placeholder" component initially so we can try and "prefetch" the expected size for your component. This is to avoid any unnecessary deep tree renders. If you feel this is not an issue for your component case and you would like to get an eager render of 131 | your component then disable the placeholder using this config option. 132 | 133 | > NOTE: You can set this globally. See the docs on first render. 134 | 135 |
136 | 137 | --- 138 | 139 | ## Component Usage 140 | 141 | We provide a "render props pattern" based component. You can import it like so: 142 | 143 | ```javascript 144 | import { SizeMe } from 'react-sizeme' 145 | ``` 146 | 147 | You then provide it either a `render` or `children` prop containing a function/component that will receive a `size` prop (an object with `width` and `height` properties): 148 | 149 | ```javascript 150 |
170 | 171 | --- 172 | 173 | ## HOC Usage 174 | 175 | We provide you with a higher order component function called `withSize`. You can import it like so: 176 | 177 | ```javascript 178 | import { withSize } from 'react-sizeme' 179 | ``` 180 | 181 | Firstly, you have to call the `withSize` function, passing in an optional [configuration](#configuration) object should you wish to customise the behaviour: 182 | 183 | ```javascript 184 | const withSizeHOC = withSize() 185 | ``` 186 | 187 | You can then use the returned Higher Order Component to decorate any of your existing Components with the size awareness ability: 188 | 189 | ```javascript 190 | const SizeAwareComponent = withSizeHOC(MyComponent) 191 | ``` 192 | 193 | Your component will then receive a `size` prop (an object with `width` and `height` properties). 194 | 195 | > Note that the values could be undefined based on the configuration you provided (e.g. you explicitly do not monitor either of the dimensions) 196 | 197 | Below is a full example: 198 | 199 | ```javascript 200 | import { withSize } from 'react-sizeme' 201 | 202 | class MyComponent extends Component { 203 | render() { 204 | const { width, height } = this.props.size 205 | 206 | return ( 207 |
252 | 253 | --- 254 | 255 | ## Under the hood 256 | 257 | It can be useful to understand the rendering workflow should you wish to debug any issues we may be having. 258 | 259 | In order to size your component we have a bit of a chicken/egg scenario. We can't know the width/height of your Component until it is rendered. This can lead wasteful rendering cycles should you choose to render your components based on their width/height. 260 | 261 | Therefore for the first render of your component we actually render a lightweight placeholder in place of your component in order to obtain the width/height. If your component was being passed a `className` or `style` prop then these will be applied to the placeholder so that it can more closely resemble your actual components dimensions. 262 | 263 | So the first dimensions that are passed to your component may not be "correct" dimensions, however, it should quickly receive the "correct" dimensions upon render. 264 | 265 | Should you wish to avoid the render of a placeholder and have an eager render of your component then you can use the `noPlaceholder` configuration option. Using this configuration value your component will be rendered directly, however, the `size` prop may contain `undefined` for width and height until your component completes its first render. 266 | 267 |
268 | 269 | --- 270 | 271 | ## Examples 272 | 273 | ### Loading different child components based on size 274 | 275 | ```javascript 276 | import React from 'react' 277 | import LargeChildComponent from './LargeChildComponent' 278 | import SmallChildComponent from './SmallChildComponent' 279 | import sizeMe from 'react-sizeme' 280 | 281 | function MyComponent(props) { 282 | const { width, height } = props.size 283 | 284 | const ToRenderChild = height > 600 ? LargeChildComponent : SmallChildComponent 285 | 286 | return ( 287 |
302 | 303 | --- 304 | 305 | ## Server Side Rendering 306 | 307 | Okay, I am gonna be up front here and tell you that using this library in an SSR context is most likely a bad idea. If you insist on doing so you then you should take the time to make yourself fully aware of any possible repercussions you application may face. 308 | 309 | A standard `sizeMe` configuration involves the rendering of a placeholder component. After the placeholder is mounted to the DOM we extract it's dimension information and pass it on to your actual component. We do this in order to avoid any unnecessary render cycles for possibly deep component trees. Whilst this is useful for a purely client side set up, this is less than useful for an SSR context as the delivered page will contain empty placeholders. Ideally you want actual content to be delivered so that users without JS can still have an experience, or SEO bots can scrape your website. 310 | 311 | To avoid the rendering of placeholders in this context you can make use of the `noPlaceholders` global configuration value. Setting this flag will disables any placeholder rendering. Instead your wrapped component will be rendered directly - however it's initial render will contain no values within the `size` prop (i.e. `width`, and `height` will be `null`). 312 | 313 | ```javascript 314 | import sizeMe from 'react-sizeme' 315 | 316 | // This is a global variable. i.e. will be the default for all instances. 317 | sizeMe.noPlaceholders = true 318 | ``` 319 | 320 | > Note: if you only partialy server render your application you may want to use the component level configuration that allows disabling placeholders per component (e.g. `sizeMe({ noPlaceholder: true })`) 321 | 322 | It is up to you to decide how you would like to initially render your component then. When your component is sent to the client and mounted to the DOM `SizeMe` will calculate and send the dimensions to your component as normal. I suggest you tread very carefully with how you use this updated information and do lots of testing using various screen dimensions. Try your best to avoid unnecessary re-rendering of your components, for the sake of your users. 323 | 324 | If you come up with any clever strategies for this please do come share them with us! :) 325 | 326 |
327 | 328 | --- 329 | 330 | ## Extreme Appreciation! 331 | 332 | We make use of the awesome [element-resize-detector](https://github.com/wnr/element-resize-detector) library. This library makes use of an scroll/object based event strategy which outperforms window resize event listening dramatically. The original idea for this approach comes from another library, namely [css-element-queries](https://github.com/marcj/css-element-queries) by Marc J. Schmidt. I recommend looking into these libraries for history, specifics, and more examples. I love them for the work they did, whithout which this library would not be possible. :sparkling_heart: 333 | 334 |
335 | 336 | --- 337 | 338 | ## Backers 339 | 340 | Thank goes to all our backers! [[Become a backer](https://opencollective.com/controlplusb#backer)]. 341 | 342 | 343 |
344 |
345 |
--------------------------------------------------------------------------------
/assets/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ctrlplusb/react-sizeme/90423fce958ed133f9c85c03ba87fb25781e62a4/assets/logo.png
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "react-sizeme",
3 | "version": "3.0.2",
4 | "description": "Make your React Components aware of their width and/or height!",
5 | "license": "MIT",
6 | "main": "dist/react-sizeme.js",
7 | "types": "react-sizeme.d.ts",
8 | "files": [
9 | "*.js",
10 | "*.md",
11 | "dist",
12 | "react-sizeme.d.ts"
13 | ],
14 | "repository": {
15 | "type": "git",
16 | "url": "https://github.com/ctrlplusb/react-sizeme.git"
17 | },
18 | "keywords": [
19 | "library"
20 | ],
21 | "homepage": "https://github.com/ctrlplusb/react-sizeme#readme",
22 | "author": "Sean Matheson ( 39 | component: ComponentType
,
40 | ) => ComponentType (
48 | component: ComponentType ,
49 | ) => ComponentTypeMy width is {size.width}px
21 | }
22 |
23 | const SizedMyComponent = withSize()(MyComponent)
24 |
25 | const onSize: WithSizeOnSizeCallback = ({ height, width }) => {
26 | if (width) {
27 | const foo = width + 1
28 | }
29 | if (height) {
30 | const foo = height + 1
31 | }
32 | // typings:expect-error
33 | const h1 = height + 1
34 | // typings:expect-error
35 | const w1 = width + 1
36 | }
37 |
38 | const foo = No given size
23 | }
24 |
25 | const { width, height } = size
26 | const result = (
27 |
28 | w: {width || 'null'}, h: {height || 'null'}
29 |
30 | )
31 | if (debug) {
32 | console.log(result)
33 | }
34 | return result
35 | }
36 |
37 | const expected = ({ width, height }) =>
38 | `w: ${width || 'null'}, h: ${height || 'null'}`
39 |
40 | const delay = (fn, time) =>
41 | new Promise((resolve, reject) => {
42 | setTimeout(() => {
43 | try {
44 | fn()
45 | } catch (err) {
46 | reject(err)
47 | }
48 | resolve()
49 | }, time)
50 | })
51 |
52 | beforeEach(() => {
53 | resizeDetectorMock = {
54 | // :: domEl => void,
55 | removeAllListeners: jest.fn(),
56 | // :: domEl -> void
57 | uninstall: jest.fn(),
58 | // :: (domeEl, callback) -> void
59 | listenTo: jest.fn(),
60 | }
61 | jest.doMock('../resize-detector.js', () =>
62 | jest.fn(() => resizeDetectorMock),
63 | )
64 | withSize = require('../with-size').default
65 | })
66 |
67 | describe('When providing a configuration object', () => {
68 | describe('And the refresh rate is below 16', () => {
69 | it('Then an error should be thrown', () => {
70 | const action = () => withSize({ refreshRate: 15 })
71 | expect(action).toThrow(/don't put your refreshRate lower than 16/)
72 | })
73 | })
74 |
75 | describe('And setting an invalid refreshMode to "debounce"', () => {
76 | it('Then an error should be thrown', () => {
77 | const action = () => withSize({ refreshMode: 'foo' })
78 | expect(action).toThrow(/refreshMode should have a value of/)
79 | })
80 | })
81 |
82 | describe('And both monitor values are set to false', () => {
83 | it('Then an error should be thrown', () => {
84 | const action = () =>
85 | withSize({ monitorHeight: false, monitorWidth: false })
86 | expect(action).toThrow(
87 | /You have to monitor at least one of the width or height/,
88 | )
89 | })
90 | })
91 | })
92 |
93 | describe('When disabling placeholders via the component config', () => {
94 | it('Then the component should render without any size info', () => {
95 | const SizeAwareComponent = withSize({ noPlaceholder: true })(SizeRender)
96 | const mounted = mount({otherProp})
364 |
365 | const mounted = mount(