[FAQ] Kibana and Emotion / CSS-in-JS usage

[cee-chen]

👋 I'm starting this discussion as a general Q&A location for EUI Emotion (or other general CSS-in-JS) usage in Kibana. The goal is of this discussion to be a one-stop linkable resource for Kibana devs.

While I may end up converting this to a wiki document at some point, I opted for a GitHub discussion now to allow others to ask questions, as well as to account for the fact that things are currently in flux (e.g. EUI's Emotion migration is still ongoing, and Kibana currently supports more than one CSS-in-JS but may not in the future).

[cee-chen]

What's the difference between the css imported from @emotion/react and @emotion/css?

@emotion/css is the vanilla JS version of Emotion. It does not require any babel setup. It generates a css- prefixed className with the attached styles, which can be applied directly to vanilla JS DOM nodes or passed to a React className={} prop, e.g.

import { css } from '@emotion/css';
const styles = css`
  color: red;
`;
<EuiComponent className={styles} />

@emotion/react is mostly syntactical sugar on top of the vanilla JS library. It allows usage of the css prop, which handles setting the generated CSS onto the underlying component's className, and automatically concatenates any other css styles passed onto the component together into a single ruleset for you. Example:

import { css } from '@emotion/react';
const styles = css`
  color: red;
`;
<EuiComponent css={styles} />

Please note that @emotion/react usage requires a babel preset setup, and that Kibana plugins already set up to use styled-components cannot use both styled-components and @emotion/react at the same time.

When should I use one vs the other?

In general, when working directly in React/JSX, we recommend using @emotion/react for the nicer css prop syntactical sugar.

For consistency, we recommend using @emotion/css only when necessary. Examples of necessary (but hopefully rare) use-cases:

• When styling raw JS DOM nodes
• If your Kibana plugin is set up with styled-components, it will not support @emotion/react and you must use @emotion/css instead
• If, for some reason, you absolutely do not want your styles to be automatically concatenated with other Emotion styles into a single selector, and want it to remain its own separate className/selector

[cee-chen]

Can I use both styled-components and @emotion/react at the same time?

No. If your Kibana plugin uses babel to compile styled-components (please see this file/regex to check if your plugin is listed: https://github.com/elastic/kibana/blob/main/packages/kbn-babel-preset/styled_components_files.js), you cannot use @emotion/react.

styled-components and @emotion/react are incompatible and Kibana can't use the babel plugins for both on the same code. While Kibana will not actively throw if you try to do so, and may actually attempt to (very inconsistently) render some Emotion styles, this is actually a bug on Emotion's end - they drop some validation in NODE_ENV=production which allows their styles to sometimes be applied even when they're not supposed to. You will still see missing CSS, however, and you should be careful not to use both. The giveaway is if you see Styled in the classNames of your component DOM.

If you still wish to use Emotion while your plugin is setup for styled-components, all is not lost - you can use vanilla JS @emotion/css passed to the className prop in the interim.

Should I migrate my plugin away from styled-components to Emotion?

EUI has started initial talks with discussing this topic with KibanaOps. While it's currently a per-team decision and it's not absolutely crucial that all teams migrate to Emotion, EUI would generally recommend/suggest moving towards it.

It's likely that as a whole, we should move Elastic repos towards a single CSS-in-JS library both for consistency and ease of support. For one, Kibana will no longer need to implement two separate babel setups or sets of dependencies.

Because Emotion is the CSS-in-JS library that EUI has chosen, it's also worth considering that:

• EUI is more able to help assist with or debug styling issues in Emotion over styled-components
• EUI exports Emotion style utilities that we do not have available for styled-components
• EUI has already set up cache providers for Emotion in, which help control where styles render on the page & can determine specificity/order, that we do not have set up for styled-components

If your team strongly prefers the styled syntax, please let us know! While we don't use it ourselves, we could potentially help you with getting @emotion/styled set up.

[breehall]

Should I use the css or style attribute for inline styling?

While we aren't enforcing this by any means, we would recommend using css over style in most cases.

• css is more flexible and allows you to add styles with selectors (e.g. :first-child, & > .some__child, &:hover).
• Using css also provides access to the EUI Theme, which style does not (e.g. css={({ euiTheme }) => ({ padding: euiTheme.size.m })}).

The only scenario which we would strongly recommend using style over css is if the direct CSS value is derived from a prop that has no constraint (e.g. css={{ color: props.color }}). Emotion generates a class for each possible permutation, which would not be efficient.