What's missing from the docs?

[aleclarson]

I'll be rewriting the docs from scratch, so I'd like to know! ✌️

Some examples:

• A section that didn't make sense or felt incomplete
• An edge case that isn't mentioned
• A guide that explains how to use react-spring for a specific purpose

[joeshub]

Hi, First of all, Thanks for all your work! this is an amazing library, and the docs are pretty great already. I started learning react-spring this year, and will say that it took a while for the concepts to sink in and now I love it and feel like I can actually understand it and have built a few things with it in production.

Here are a few ideas

• Would be great to keep the v8 version for reference.

• It would be awesome if we can integrate some sort of visualization for the config, here's an example

• I'm not sure if its possible, but it would be super handy to break up the Common API into sections and sub-sections, and have an example for each one. Kinda like MDN e.g. a page for currentTarget under event. Or in this case a page for onStart under common.

• Controller class and examples

• Oh also having a migration section would be helpful for going from 8 to 9. It took me a minute to realize to is the new interpolate etc.

[aleclarson]

Great points, thank you!

[sgrezza]

Based on some common posts on Spectrum:

• Docs should more-blatantly mention usage with Styled Components/Emotion (and provide an example)
• Docs should more-blatantly mention usage with React Native and provide an example of which I have, albeit convoluted

If I may let conjecture drive: these posts come from the small problem of the docs' lack of explicit examples using non-div components, such as those that come from using Styled Components (i.e. <MyStyledHeader/>) and React Native's <View> and <Text> element; none of which can be suffixed onto the animated function from React Spring.

[aleclarson]

Great points, thank you! Be sure to bump the discussion too. ;)

[christianvonlehe]

It would be great to have some examples of an infinite loop animation

[ElForastero]

Would be nice to have more examples of usage of lifecycle methods.

Like this one with scrolling to the top. It's not trivial and after reading the docs I didin't have a clear vision on how to do this.

const Component = () => {
  const [, setY] = useSpring(() => ({ y: 0 }));
  
  return (
    <button
      onClick={() => {
        setY({
          y: 0,
          from: { y: window.scrollY },
          onChange: ({ y }) => ref.current.scrollTo(0, y),
        });
      }}
    >
      back to top
    </button>
  );
};

[coreyward]

Honestly it would be helpful to focus on documenting hooks and functions at a fundamental/core level. The existing documentation is full of wonky examples with poor naming and very little fundamentals. For example, the docs for useTransition don't have any mention of what arguments useTransition accepts, just a demo taking “item”, a function, and a config object, then they go on to demonstrate the use in ways incongruent with the naming.

[bradwoods]

I've made a list of simple examples that might help - https://bradwoods.io/guides/react-spring

[tomdohnal]

I'd really appreciate giving some insight into manually animating using the Controller class for cases where you can benefit from a more imperative approach

[rosofo]

I don't see anything about testing strategies. Animations are tricky to test of course, also often tricky to get working.

• React-spring's internal properties are complex. I sometimes try to inspect them with the dev tools to see what's changing over time but it's cumbersome. Does it expose shorthand properties that I'm missing?

• What could tests look like? Could they await animations in a similar fashion to to: async animation => functions?

[omasback]

Would be nice to have a formal and exhaustive API reference with simple examples. Like lodash or react-router. Document everything! Right now feels very ad hoc and incomplete. animated is basically undocumented and should have its own section, with examples on how to apply to custom elements.

[bradwoods]

Here's some simple examples that might help - https://bradwoods.io/guides/react-spring

[mikemajara]

Here's some simple examples that might help - https://bradwoods.io/guides/react-spring

You might want to collaborate with the docs, rather than linking your blog here multiple times.

[bradwoods]

I'll make an issue and see what people think.

[alextenb]

I volunteer to help with this. An API reference would be extremely helpful.

[csenio]

It would be great if we could have a bigger examples/recipe section. Since "declarative animations" is quite a mindset shift It only really clicked for me once I looked at a bunch of projects and two years later I still usually only look at examples over the documentation.

The current examples are amazing but something like clearer variable naming would also really help, stuff like this

const calc = (x, y) => [-(y - window.innerHeight / 2) / 20, (x - window.innerWidth / 2) / 20, 1.1]

is quite common and makes the examples harder to approach.

[csenio]

there's also a lot of undocumented / very hard to find stuff like the update or interpolate function

[MatthewCaseres]

I think showing a transition from one list to another list would be useful. It seems more common than permutations, which are covered fairly well.

[mattrossman]

A dedicated section for react-three-fiber explaining usage and patterns!

E.g. it's really hard to find that @react-spring/three or react-spring/three even exists

[mikemajara]

I have been missing thorough simple examples upon which to build. I can see how some are advanced and do not map 1:1 to other libraries or plain css which made it harder to grasp.

Do and do not, can and cannot, are also useful. For example: in Up-front interpolation, one can read that "Springs take pretty much everything, they don't just handle numbers.", making explicit what can they not animate (e.g. displays, attributes like flex or grids, etc) would make it clearer for all types of audience, not just those that are already experienced in animations. Questions like this one in spectrum suggest the info is there, it is just hard to make sense out of what's written.

[VICODE-YT]

How can I contribute to the docs?

[mahmoud-alfall]

it would be helpful to add a section about scroll triggering like that https://youtu.be/X7IBa7vZjmo

[bstro]

imo it'd be nicer UX if, upon clicking any navigation in the docs, the scroll position didn't move the user back up to the hero area. <3