Emotion: react-emotion vs emotion - usage not clear (documentation)

[PutziSan]

Hi, before I get started, thanks for this great library.

• emotion version: 9.2.4

What you did:
introduce emotion to replace styled-components

What happened:
I get confused while following the documentation.

Problem description:

While I introduced emotion into my application it was often hard for me to understand what the best way is to write styles with emotion. Initially I wanted to use emotion because I like the use with classes and className=... much better than creating own components for it (imho better tests, seperation of concerns, ...). so, imho css > styled.

Later you will introduce styled-components via react-emotion, which for me is in principle == styled-components™. So the name (react-emotion) suggests that you also recommend styled components for use with React, which is exactly what I didn't want.

And later in your documentation you seem to treat react-emotion and emotion more or less interchangeably. For example, at first I thought keyframes could only be used in react-emotion: Is there a particular reason why you use react-emotion and not emotion here?

I was also unsure if I could use css as functions to implement dynamic content like Theming (without the template-literal being within my React component).

const color = theme => css`color: ${theme.color}`;

const MyComp = props => <div className={color(props.theme)} />

But many answers in the issues show exactly this usage, accordingly I think that this usage is okay and nothing that isn't actually intended by you.

Suggested solution:

You may not always make styled component and css documentation in pairs on one page and/or insert a section that explains why you provide both options and what you think is the best way to use emotion.

It would also be cool if you included the use of Theming and dynamic content with css in your documentation.

[Andarist]

APIs such as css & keyframes are part of emotion, but in general react-emotion re-exports everything that is already in emotion so react-emotion can just use a single package instead of importing some things from emotion & some from react-emotion.

We do not have any strict recommendations on styling with emotion/react-emotion. It's a toolkit that u can use however you want - most people like using styled to create styled-components-like components, but it's ofc not enforeced so you can just stick to using bare emotion.

Because emotion itself is react-independent it doesn't really have theming built in (with react-emotion the story is different, because theme is naturally & automatically propagated through a react tree) so you have to "wire up" things urself. "Theming" with emotion really boils down to just making parametrized functions which return css results (I guess you still can use ThemeProvider + withTheme but in general it's still manual wiring up things to propagate theme).

[PutziSan]

Hi, thanks for your answer.

Those things you wrote slowly became clearer to me. I just wanted to share my experiences that I had with emotion in the first 2 days and that the documentation partly unsettled me. If some of the points were added to the beginning of the current documentation, these things could be understood more clearly, easily and better from the beginning. For example, areas that briefly clarify the following topics:'Motivation for emotion','how to start with emotion' or'how to read this documentation','emotion with react'.

As I said, I really like the approaches of emotion and think that there are clear advantages over other solutions. However, one could present some topics that are not currently illuminated more clearly and draw a clearer distinction between emotion and react-emotion (if, for example, the Theming solution can only be used with react-emotion, one could present this accordingly and should not be in the "pure" emotion area).

As I said, it's just my experiences and thoughts on the topic and maybe others will start as well (For example #113 #381 #287 #291 go in that direction). It is not an appeal that everything should be done differently, but you could use these ideas for further developments, otherwise you are welcome to close this issue ;)

[deadcoder0904]

Agreed, docs aren't as much clear as styled-components or glamarous keeping aside the beautiful websites. I think now that glamarous is deprecated, docs of emotion can be made as good as it in-terms of presenting it like Search & all

[lilactown]

I agree; we are using just css, without using the react integration, and it is very unclear from the docs what requires react-emotion and what is simply a feature of the core emotion package.

I think it would be really helpful to have docs that only talked about the core emotion package, and then a separate doc for react-emotion that gave a high level overview of how to use emotion in conjunction with the styled HOC.

[FezVrasta]

With emotion@10 the difference is now pretty clear, the documentation explains emotion is framework agnostic while the @emotion/ packages are for React.

[cyrilchapon]

While the docs State it, Why on Earth @author package prefixing would mean "for react". That' so much misleading