You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+25-53Lines changed: 25 additions & 53 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,25 +2,25 @@
2
2
3
3
[![npm package][npm-badge]][npm]
4
4
5
-
If you're looking for a lightweight, high-performance, easy-to-use way to render long lists efficiently in React, you found it.
5
+
ReactSmartScroll is a lightweight, high-performance, easy-to-use way to render long lists efficiently in React. It only renders the visible rows, with a few buffer rows above and below.
6
6
7
-
"Smart Scrolling" only renders the visible rows, with some buffer rows above and below. It supports dynamic height rows.
7
+
ReactSmartScroll is un-opinionated, with minimum configuration. It has automatic support for variable height rows, even if they change height at runtime due to resizing, expanding, etc.
8
8
9
-
It is un-opinionated, and gives exactly you what you need with minimum configuration. Namely, fast rendering of long lists, and automatic support for variable height rows, even if they change height at runtime due to resizing, etc.
10
-
11
-
**This component uses React Hooks, so you'll need to be running React 16.8.x or above.**
9
+
**This component uses React Hooks, so it requires React 16.8.x or above.**
12
10
13
11
## How To Use
14
-
You can check the `demo` folder for some example code, but here's how it works.
12
+
ReactSmartScroll is designed to be simple to use. You can check the `demo` folder for an example, as well.
15
13
16
-
#### Props
17
-
There are no required props. If you pass nothing, you'll get nothing.
14
+
At its most basic, you pass an array of data and a row component to render the items in the array.
18
15
16
+
All of the props are optional. If you don't provide any data or a row component, it won't render anything, but it won't cause any errors, either.
17
+
18
+
#### Props
19
19
-`className` - A css className that will be applied to the component.
20
-
-`data` - An array of items - each item will be passed to your row component. See below.
21
-
-`row` - Your row component function/class.
22
-
-`rowHeight` - Starting row height (100 by default) - it starts with this as an estimate and adjusts to what the real height of each row is as you scroll.
23
-
-`style` - A style object applied to the component if you prefer this to a className.
20
+
-`data` - An array of items to be passed to your row component.
21
+
-`row` - Your row component.
22
+
-`rowHeight` - Starting row height (100 by default) - it starts with this as an estimate for all rows, and then measures and caches the actual height of each row is as you scroll.
23
+
-`style` - A style object applied to the component if you prefer using inline styling instead of css.
24
24
-`...rowProps` - Any additional props you pass will be applied to your row components, for example `onClick`.
The `data` array can be made up of whatever you want. ReactSmartScroll does not care. It simply passes the data directly to your row component as-is.
46
-
47
-
If you pass an object with an `id` property, it will use the id as the key for each row, which can be more efficient than using the row index. But you don't have to.
45
+
The `data` array can be made up of objects or strings. ReactSmartScroll passes the items in the array directly to your row component so you have complete freedom in how the rows render. If you pass an object with an `id` property, it will use the `id` as the key for each row, which can be more efficient than using the row index.
48
46
49
47
Your row component receives the following props:
50
48
-`data` - The item in the data array that corresponds to this row.
51
-
-`height` - The current measured height of this row. It's provided mainly for debugging, but if you have a use for it, go for it.
52
-
-`rowIndex` - The index of the item in the data array. Same as height - provided for debugging, use if you like.
53
-
-`rowRef` - NECESSARY! You need to include `ref={rowRef}` prop on your row component's container element, whatever that is. This is how it computes the height of each row. Even if your rows are all the same height, you need to include this in your row component. It makes the rendering more efficient.
54
-
-`...rowProps` - Any additional props you passed to the ReactSmartScroll component will be available on every row by the same name. Just don't overwrite the 4 passed props. Or do and watch things break. Or not. I haven't tried it myself.
55
-
56
-
## Important!
57
-
This component does not have any default styling. You need to provide at least two properties in the css class or the style object. I didn't want to assume anything and wanted to give complete flexibility in how to implement it.
49
+
-`height` - The current measured height of the row. It's provided for debugging or if you have a use for it.
50
+
-`rowIndex` - The index of the item in the data array. Also provided for debugging, use if you like.
51
+
-`rowRef` - *required* You need to include `ref={rowRef}` prop on your row component's container element.
52
+
-`...rowProps` - Any additional props you passed to the ReactSmartScroll component will be available on every row.
58
53
59
-
1.`height` - You need to provide a height or it won't work. `height: 100%` may not be predictable. Favor `calc()`.
60
-
2.`overflow-y` You must include `auto` or `scroll`.
54
+
ReactSmartScroll does not come with any default styling. Two properties are required in the css class or the style object. This provides complete flexibility in how its implemented.
61
55
62
-
I recommend rendering your list and figuring out what the average row height will be and setting rowHeight to that.
56
+
1.`height` - You need to provide a height or it won't work. Due to the way CSS works with padding, `height: 100%` will not work. You can use a specific height, or `calc()`.
57
+
2.`overflow-y` Set this to `auto` or `scroll`.
63
58
64
59
## How It Works
65
-
It's simple, really. And that's why it's so fast. And it's why I think other solutions are way over-engineered... but I digress.
66
-
67
-
It renders enough rows to fill the visible space of the scroll area. It measures the height of each of the visible row and caches it as you scroll (or resize) so that the next render of the same row is more efficient.
68
-
69
-
It always makes sure to include enough buffer above and below to never have an empty space while you scroll up and down.
60
+
ReactSmartscroll renders enough rows to fill the visible space of the scroll area, plus an extra one above and below. It measures the height of each of the visible row and caches that height as you scroll (or resize) so that the next render of the same row is more efficient. It simulates the total height of all the items by adjusting the padding top and bottom of the div that contains the rows as you scroll.
70
61
71
-
It accomplishes simulating the total height of all the items by padding the top and bottom of the div that contains the rows. That's it! I told you it was simple. This is also why you have to set the height to a specific value and not a percentage. Percentage heights don't get along with css padding. It's not a bug, it's a feature.
72
-
73
-
There's no wrapper divs for your rows, absolute positioning, or polyfills for element observables. It's literally just two divs wrapped around your row components. I just did the hard part of figuring out the math for calculating the height.
74
-
75
-
And yes, if you look at the source, you'll see I'm using for loops for the top and bottom padding calculations. That's because they're an order of magnitude faster than map/reduce and since they're being called every time you scroll or resize, they needed to be high performance, especially if you have a really long list.
76
-
77
-
If you know how to speed up the calculations and make them faster way, please let me know.
78
-
79
-
Finally, if you're wondering why I have to add 17 pixels to the bottom padding, you're not alone. I have no idea why that's required for the calculations to be correct, but it is. The mysteries of CSS never end. If you know the answer, tweet it at me.
62
+
Unlike other virtual scrolling components/libraries out there, there are no unnecessary wrapper divs for your rows, it doesn't use absolute positioning, and doesn't require any polyfills.
80
63
81
-
#### Disclaimer
82
-
The latest version of Firefox doesn't seem to honor React's rendering speed with `useLayoutEffect()` or `useEffect()`, so if you grab the scrollbar and scroll up and down really fast, you'll see blank space momentarily. Not sure why Firefox hates React, but it's not my bug. Chrome doesn't have this problem.
83
-
84
-
The good news is that using the mouse wheel to scroll looks good in all browsers.
64
+
#### Firefox Note
65
+
The latest version of Firefox doesn't seem to keep up with React's rendering speed with `useLayoutEffect()` or `useEffect()`, so if you grab the scrollbar and scroll up and down really fast, you'll see blank space momentarily. Other browsers don't appear to have this problem. Using the mouse wheel to scroll looks good in all browsers.
85
66
86
67
## Future Stuff
87
-
I'm working on the ability to jump to a specific row in the list. This isn't as easy as you might think. It will probably be a prop called `startIndex` or something. I haven't decided that, yet.
68
+
I'm working on the ability to scroll to a specific row in the list programmatically.
88
69
89
-
If you have any feature ideas, be sure to let me know in the github issues. As long as it doesn't bloat the code, I'll consider it.
90
-
91
70
I hope you enjoy using this component as much as I enjoyed making it!
0 commit comments