Improving documentation for react-simplebar

[carpben]

I'm using "react-simplebar". This is a helpful well performing library, that rightly gains a lot of popularity in recent months. However, current documentation seems insufficient and misleading.

Is your feature request related to a problem? Please describe.
Having a difficult time customizing the react component to get a ref, and customize the appearance (style and when it shows, width) of the scrollbar. Trying docs suggestion did not work and had to find alternatives.

Describe the solution you'd like
Updating documentation for how to use the react version of the library.

Additional context

1. According to the docs:
   

When trying to pass render function as props no children were rendered to the dom. Looking at various issues I found this solution:

<SimpleBar  scrollableNodeProps={nodeProps}  >{children}</SimpleBar>

Which allows to pass ref and onScroll props to the scroll wrapper.
2) Trying to pass other props according to the documentation resulted in no effect on the screen.

3) A clear documentation of how to customise appearnce of the component could be helpful.
4) It isn't trivial how to embed this component in terms of style and CSS. Perhaps a few best practices could be recommended.
5)It should be mentioned where users should look for support - here on github or on Stackoverflow. If on SOF, perhaps a new tag could be created.

I'd be happy to contribute, though I am new to this library and some of it still isn't clear to me.

[Grsmto]

Hey,
Thanks for your report, it's absolutely right. Especially since the documentation available right now in the readme is related to the new alpha version which is not released yet, so not matching to what people are using. This is a workflow mistake on my side and that's why 1) and 2) are not working. Edit: doc is now matching the latest version.

3. A clear documentation of how to customise appearance of the component could be helpful.

Right, we should have some recipes of CSS snippets showing how to do usual things, like change scrollbar color, thickness, etc.

4. It isn't trivial how to embed this component in terms of style and CSS.

Unfortunately this really depends on your stack: if you use something like Create React App or Gatsby, just importing the css file like written in the doc will work straight away.
If you are using a custom Webpack setup or some other setup, you will probably need a css loader...But it's hard to guide users on that. Any recommendation?

5. Support

Right.
I don't think the plugin is popular enough to have answers on SO, so in the Github issues is probably best (and that's what people are doing anyway).

[carpben]

Thanks @Grsmto for your response.

As for number 4, I did not articulate it well. I replaced the scroll wrapper we previously used with the simplebar and originally the bar didn't work on certain views. It took me some time to understand what was going on. I solved it by adding "overflow:hidden;" to the parent div. So I thought we might want to give some best css practices to handle this gracefully. Perhaps we can show the diagram below.

You raised another issue. Some projects such as ours don't use css files, but use css in js. usually css in js libraries have solutions for this. Emotion for example has an injectGlobal function that allows injecting global style from anywhere in your code. I'd be happy to suggest a solution for this scenario.

[krachtstefan]

Especially since the documentation available right now in the readme is related to the new alpha version which is not released yet, so not matching to what people are using.

Just to understand, simplebar-react@1.3.0-alpha.0 is the "new" react version which will introduce this api, right?

[Grsmto]

@krachtstefan no it's not. There is no unreleased alpha version at the moment. The latest version is simplebar-react@2.0.9 and should match the documentation.
The comment you are quoting is 1 month old so that was released in the meanwhile!

[krachtstefan]

I was using simplebar-react@1.3.0-alpha.0 with the render props example from the readme and I just tried to upgrade to simplebar-react@2.0.9 today and it breaks with the following error:

Uncaught TypeError: Cannot read property 'offsetWidth' of null at SimpleBar.recalculate (simplebarcore.esm.js:477) at invokeFunc (index.js:160)

I made a sandbox for illustration (same example but different simplebar-react dependency)
working with 1.3.0-alpha.0
not working with 2.0.9

Am I using it wrong 🤔

[krachtstefan]

Wow, that was quick! Thanks for this repository, it really solves an annoying problem with a very easy to use component! 🙏