Skip to content

Commit e671d1b

Browse files
committed
update README
1 parent 0cd71ee commit e671d1b

File tree

1 file changed

+34
-17
lines changed

1 file changed

+34
-17
lines changed

README.md

Lines changed: 34 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,19 @@ under the hood. It's a peer dependency so install like so:
1717

1818
`npm install gl-matrix react-css-transform --save`
1919

20+
## Why
21+
22+
While it might be a little niche, there have been several projects over the last few years
23+
where I've thought about writing this and ended up going with a "faster", hackier
24+
solution using nested divs and manual inline calculations. Often the nested divs caused
25+
me problems with mouse and UI events. I thought I'd do it properly this time and thanks to
26+
Pest Pulse for letting me open source it.
27+
28+
If you're just doing basic transforms on a single element, you probably don't need this
29+
library. It is super useful for doing nested transformations and it can be useful on a
30+
single element if you want to ensure consistent application of the transform, scale and
31+
rotate transformations. If you hadn't noticed the order is important!
32+
2033
## Examples
2134

2235
[3D Cubes Example](https://baseten.github.io/react-css-transform/3d-cubes/index.html)
@@ -156,28 +169,32 @@ to pass scale in as an object rather than a number (otherwise z will be scaled t
156169

157170
### Performance
158171

159-
When running in development mode, `propTypes` checking can cause significant performance
160-
bottlenecks particularly if running `render` in a `requestAnimationFrame`. If you're
161-
seeing performance issues, try running a production build first.
162-
163-
With standard React apps you've probably got used to declaring lambdas and object literals
164-
inline in your render method. People sometimes talk about how this is a performance hit,
165-
but realistically for standard UI where renders are mostly limited to user interaction,
166-
it's going to make no noticeable difference and the readability is worth it.
167-
168-
If you're gonna do 3D transformations every frame, or more specifically call `render` as
169-
the result of a `requestAnimationFrame` callback, you *may* want to reconsider this.
170-
Modern browsers can create and dispose of objects and arrays very quickly, but when they're
171-
disposed of the garbage collector *may* cause a janky animation. As with all
172+
The library is generally very performant, mainly as it leverages the brilliant `gl-matrix`
173+
library and obviously React's virtual DOM. There are a couple of issues it's worth being
174+
aware of though. These are mainly applicable when doing 3D transformations and/or when
175+
calling `render` in a `requestAnimationFrame` callback:
176+
177+
* When running in development mode, `propTypes` checking can cause performance bottlenecks.
178+
Chrome seems to suffer from this more than Firefox and Safari. If you're seeing
179+
performance issues, try running a production build first before going down any other
180+
rabbit holes.
181+
182+
* With standard React apps you've probably got used to declaring lambdas and object literals
183+
inline in your render method. For standard UI where renders are normally limited to user
184+
interaction, you most likely won't notice a performance hit doing this. If you're gonna do
185+
3D transformations or just a complex `render` every frame, you *may* want to reconsider
186+
this. Modern browsers can create and dispose of objects and arrays very quickly, but when
187+
they're disposed of the garbage collector *may* cause a janky animation. As with all
172188
performance optimization don't do it unless you need to. Just sayin' :)
173189

174190
### IE10 and IE11
175191

176192
IE10 and IE11 famously don't support `preserve-3d`. To a certain extent this library can
177-
help with issues here because it won't create any nested DOM elements, but will compute
178-
the correct matrices to use on a single set of children. However, you will still very
179-
likely run into z order issues as IE will maintain DOM / z-index order over 3D z position,
180-
so doing complex 3D transformations in these browsers is not really possible.
193+
help with issues here because it doesn't create any nested DOM elements, but computes
194+
matrices to use on a single set of children. However, you will still very likely run into
195+
z order issues as IE will maintain DOM / z-index order over 3D z position. This
196+
restriction makes doing complex 3D transformations in these browsers impossible.
197+
Ultimately it depends on your use case and whether you have to support them.
181198

182199
## How it works
183200

0 commit comments

Comments
 (0)