[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?

Yes, teams should begin migrating. While we don't yet have a set target date for moving entirely away from styled-components in Kibana, we expect to share one soon.

Our goal is to standardize on Emotion as our CSS-in-JS solution in Kibana. This will ensure consistency, easier support, and a unified theming system across the platform.

Here are a few key points to consider:

• The EUI team 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

As a simple first step in this transition, consider using @emotion/styled. This allows you to keep the familiar styled syntax while aligning with the Emotion ecosystem

We've also found this guide to be a useful reference for migration.

[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.

[cee-chen]

Migrating from Sass to CSS-in-JS

This section of the FAQ is meant as a handy reference/cheatsheet on how to migrate specific Sass variables and mixins to their Emotion counterparts.

Variables

Sizes

For a full list of tokens, see https://eui.elastic.co/#/theming/sizing/values

Sass	CSS-in-JS
$euiSize	useEuiTheme().euiTheme.size.base
$euiSizeM	useEuiTheme().euiTheme.size.m
$euiSizeXS/XL/etc	All of these sizes convert to lowercase equivalents, euiTheme.size.xs/.xl etc
N/A	Note that there are 3 new sizes in our CSS-in-JS tokens to take advantage of, that may help simplify Sass math/calcs: xxs (2px), xxxl (48px) , and xxxxl (64px)

Performing math on size tokens

It's worth highlighting that these size tokens return CSS strings and not numbers. This means something like $euiSize * 10 requires much more syntactical sugar than it previously did in Sass. If you need to calculate a custom size, you can use one of these 3 methods:

1. euiTheme.base returns a number (16 by default) that can have math performed on it, e.g:

const width = `${useEuiTheme().euiTheme.base * 10}px`; // '160px'

2. EUI offers a mathWithUnits utility that preserves the unit of the passed string. Example usage:

import { mathWithUnits } from '@elastic/eui';

const SomeComponent = () => {
  const { euiTheme } = useEuiTheme();

  const width = mathWithUnits(euiTheme.size.base, (x) => x * 10); // Returns '160px'

  // The util also accepts multiple tokens, e.g.
  const height = mathWithUnits([euiTheme.size.xl, euiTheme.size.xs], (x, y) => x + y); // Returns '44px'
}

3. You can also prefer to use CSS's built-in calc() function, e.g.

css`
  width: calc(${euiTheme.size.base} * 10);
`

Colors

For a full list of tokens, see https://eui.elastic.co/#/theming/colors/values

Sass	CSS-in-JS
$euiColorPrimary/$euiColorSuccessText/etc	useEuiTheme().euiTheme.colors.primary / useEuiTheme().euiTheme.colors.successText (same lowercase naming scheme for all brand colors)
$euiColorMediumShade/EmpyShade/etc	useEuiTheme().euiTheme.colors.mediumShade/.emptyShade (same naming scheme for all shade colors)
$euiPageBackgroundColor	useEuiTheme().euiTheme.colors.body
$euiTextColor	useEuiTheme().euiTheme.colors.text
$euiTitleColor	useEuiTheme().euiTheme.colors.title
$euiTextSubduedColor	useEuiTheme().euiTheme.colors.subduedText
$euiColorDisabled/$euiColorDisabledText	useEuiTheme().euiTheme.colors.disabled/.disabledText
$euiColorHighlight	useEuiTheme().euiTheme.colors.highlight
$euiColorGhost	useEuiTheme().euiTheme.colors.ghost (consider replacing this with fullShade/emptyShade instead)
$euiColorInk	useEuiTheme().euiTheme.colors.ink (consider replacing this with fullShade/emptyShade instead)

Color palettes:

$euiColorPaletteBlind is now a function that generates a customizable array of palettes. To use it as-is from its previous Sass incarnation, simple invoke it with no arguments passed:

import { euiColorPaletteBlind, euiPaletteColorBlindBehindText } from '@elastic/eui';

// Note that these utils can be called statically / outside of hooks or react components
const visColors = euiColorPaletteBlind();
const visBackgroundColors = euiPaletteColorBlindBehindText();

const SomeComponent = () => <div css={{ color: visColors[0], backgroundColor: visBackgroundColors[1] }} />

For a full list of arguments, see https://eui.elastic.co/#/utilities/color-palettes.

Sass	CSS-in-JS
$euiColorVis0	euiColorPaletteBlind()[0]
$euiColorVis1_behindText	euiPaletteColorBlindBehindText()[1]
...	And so forth for all numbers.

Typography

For a full list of tokens, see https://eui.elastic.co/#/theming/typography/values

Sass	CSS-in-JS
$euiFontWeightBold	useEuiTheme().euiTheme.font.weight.bold (same naming scheme for all weights)
$euiFontFamily	useEuiTheme().euiTheme.font.family
$euiCodeFontFamily	useEuiTheme().euiTheme.font.familyCode
$euiFontFeatureSettings	useEuiTheme().euiTheme.font.featureSettings
$euiLineHeight	useEuiTheme().euiTheme.font.lineHeightMultiplier
$euiTextScale	useEuiTheme().euiTheme.font.scale

Unfortunately, font sizes are no longer static tokens, and must be calculated using a function/hook instead. See the below "Typography" mixin section.

Z-index levels

For a full list of tokens, see https://eui.elastic.co/#/theming/more-tokens#levels

Sass	CSS-in-JS
$euiZLevel0	useEuiTheme().euiTheme.levels.content
$euiZLevel1	This can be either levels.header, levels.flyout, or levels.maskBelowHeader, depending on the context/use case.
$euiZLevel2	useEuiTheme().euiTheme.levels.menu
$euiZLevel6	This can be either levels.mask or levels.navigation, depending on the context
$euiZLevel8	useEuiTheme().euiTheme.levels.modal
$euiZLevel9	useEuiTheme().euiTheme.levels.toast
$euiZLevel3, $euiZLevel4, $euiZLevel5, $euiZLevel7	With our Emotion conversion, we've deprecated the use of generic numbered levels, so these levels no longer exist. We recommend adjusting to the nearest semantic meaning, or if necessary, using a static number (if no meaning is associated with EUI components).

A quick note about math with z-index levels - while they're typed in our theme as potentially being either a string or number (the default type for CSS properties), the returned tokens are numbers and can have math performed on them as-is (e.g. addition).

Borders

For a full list of tokens, see https://eui.elastic.co/#/theming/borders

Sass	CSS-in-JS
$euiBorderRadius	useEuiTheme().euiTheme.border.radius.medium
$euiBorderRadiusSmall	useEuiTheme().euiTheme.border.radius.small
$euiBorderWidthThin	useEuiTheme().euiTheme.border.width.thin
$euiBorderWidthThick	useEuiTheme().euiTheme.border.width.thick
$euiBorderColor	useEuiTheme().euiTheme.border.color
$euiBorderThin	useEuiTheme().euiTheme.border.thin
$euiBorderThick	useEuiTheme().euiTheme.border.thick
$euiBorderEditable	useEuiTheme().euiTheme.border.editable

Animations

For a full list of tokens, see https://eui.elastic.co/#/theming/more-tokens#animation

Sass	CSS-in-JS
$euiAnimSlightBounce	useEuiTheme().euiTheme.animation.bounce
$euiAnimSlightResistance	useEuiTheme().euiTheme.animation.resistance
$euiAnimSpeedExtraFast	useEuiTheme().euiTheme.animation.extraFast
$euiAnimSpeedFast	useEuiTheme().euiTheme.animation.fast
$euiAnimSpeedNormal	useEuiTheme().euiTheme.animation.normal
$euiAnimSpeedSlow	useEuiTheme().euiTheme.animation.slow
$euiAnimSpeedExtraSlow	useEuiTheme().euiTheme.animation.extraSlow

Form variables ⚠️

EUI currently does not have a migration path for $euiForm Sass variables. Until we have one, we will not be deprecating these variables.

Mixins

Typography

As mentioned above, $euiFontSize* tokens no longer exist. Instead, we require using a utility that returns both a fontSize and lineHeight in object format. In general, if possible, we strongly recommend using EuiText and EuiTitle instead of directly applying font sizes via CSS.

If you absolutely cannot use a component, we generally recommend the useEuiFontSize() hook to replace font styling:

import { useEuiFontSize } from '@elastic/eui';
import { css } from '@emotion/react';

const SomeComponent = () => {
  const cssStyles = [
    useEuiFontSize('l'),
    css`color: red;`
  ];

  return <div css={cssStyles} />
}

Warning

Please note that line-heights have increased from Sass to CSS-in-JS. This appears to have been an intentional change/decision from Caroline.
If you only want the fontSize portion of the utility and not the lineHeight, you can split out the object key like so:

import { useEuiFontSize } from '@elastic/eui';
import { css } from '@emotion/react';

const SomeComponent = () => {
  const euiThemeContext = useEuiTheme();
  const cssStyles = css`
    font-size: ${useEuiFontSize('l').fontSize};
    line-height: 1;
  `;

  return <div css={cssStyles} />
};

Sass	CSS-in-JS
@include euiFontSizeS/L/etc	useEuiFontSize('xxxs' through 'xxl')
@include euiFont	Deprecated. Use font-family: ${euiTheme.font.family}; or font-weight: ${euiTheme.font.weight.regular}; if necessary instead
@include euiCodeFont	Deprecated. Use font-family: ${euiTheme.font.familyCode}; instead
@include euiText	Deprecated. Use <EuiText /> or if necessary, color: ${euiTheme.colors.text} instead
@include euiTitle	Deprecated. Use <EuiTitle /> instead (strongly recommended) If absolutely necessary, you may reach into the EuiTitle component via import { euiTitle } from '@elastic/eui/lib/components/title/title.styles';, but this is generally not recommended as Kibana has issues typing @elastic/eui/lib
@include euiTextTruncate and @include euiTextBreakWord	Consider simply applying .eui-textTruncate or .eui-textBreakWord as a vanilla className (simplest option). Or, import { euiTextBreakWord, euiTextTruncate } from '@elastic/eui'; and use it as css={euiTextTruncate()}

See https://eui.elastic.co/#/theming/typography/utilities for a full list of className utilities and documentation.

Responsive

EUI's breakpoint utilities have been generally enhanced to exceed their Sass capabilities. With that in mind, we recommend a more nuanced approach to migrating media queries:

Sass	CSS-in-JS
@include euiBreakpoint('s', 'm')	useEuiBreakpoint(['s', 'm'])
Media queries ending with @include euiBreakpoint(..., 'xl') e.g., @include euiBreakpoint('m,' 'l', 'xl')	useEuiMinBreakpoint('m') We recommend preferring a single min/max breakpoint, as this helps account for themes with custom breakpoints
Media queries beginning with @include euiBreakpoint('xs', ...) e.g., @include euiBreakpoint('xs', 's')	useEuiMaxBreakpoint('m') See above. If converted from @euiBreakpoint, should be a size higher than the ending size

Example usage:

import { useEuiMinBreakpoint, useEuiMaxBreakpoint, useEuiBreakpoint } from '@elastic/eui';

const SomeComponent = () => {
  const cssStyles = css`
    ${useEuiMaxBreakpoint('m')} {
      color: red; /* Text will be red under the 'm' breakpoint */
    }
    ${useEuiBreakpoint(['m', 'l'])} {
      color: yellow; /* Text will be yellow between the 'm and 'xl' breakpoints */
    }
    ${useEuiMinBreakpoint('xl')} {
      color: green; /* Text will be green above the 'xl' breakpoint */
    }
  `

  return <div css={cssStyles />;
}

For a list of all default breakpoints and visual demonstration of these utilities, see https://eui.elastic.co/#/theming/breakpoints/values

Shadows

For a visual demonstration of these mixins, see https://eui.elastic.co/#/theming/more-tokens#shadow

Sass	CSS-in-JS
@include euiSlightShadow	useEuiShadow('xs')
@include euiBottomShadowSmall	useEuiShadow('s')
@include euiBottomShadowMedium	useEuiShadow('m')
@include euiBottomShadow	useEuiShadow('l')
@include euiBottomShadowLarge	useEuiShadow('xl')
@include euiBottomShadowFlat	useEuiShadowFlat()
@include euiSlightShadowHover	useEuiSlightShadowHover()

Scrolling

For a visual demonstration of these mixins, see https://eui.elastic.co/#/utilities/scroll

Sass	CSS-in-JS
@include euiScrollBar	useEuiScrollBar(), or apply the .eui-scrollBar className
@include euiYScroll	useEuiOverflowScroll('y'), or apply the .eui-yScroll className
@include euiYScrollWithShadows	useEuiOverflowScroll('y', true)
@include euiXScroll	useEuiOverflowScroll('x'), or apply the .eui-xScroll className
@include euiXScrollWithShadows	useEuiOverflowScroll('x', true)

Non-hook utilities

If using a hook is onerous to migrate within the existing code for any reason (e.g. conditional returns, nested hooks, etc.), you may use non-hook versions of each utility. For example, you can import euiFontSize instead of useEuiFontSize, euiBreakpoint instead of useEuiBreakpoint, euiShadow instead of useEuiShadow, and so on and so forth.

import { euiFontSize, useEuiTheme } from '@elastic/eui';
import { css } from '@emotion/react';

const SomeComponent = ({ isLoading, hasButton }) => {
  const euiThemeContext = useEuiTheme();

  // Conditional return before css`` is used
  if (isLoading) return <LoadingComponent />;

  // Nested hook usage
  const someButton = useMemo(() => {
    if (!hasButton) return null;

    const cssStyles = css`
      ${euiFontSize(euiThemeContext, 'l')}
      color: red;
    `;

    return <button css={cssStyles}>Conditional button</button>;
  }, [hasButton, euiThemeContext]);

  return <>{someButton}{children}</>
};

Alternatively, you can also take advantage of Emotion's theme context API to obtain the current EUI theme without useEuiTheme() as a nice syntactical sugar shortcut. See also: https://eui.elastic.co/#/theming/theme-provider#consuming-with-emotions-theming

import { euiFontSize } from '@elastic/eui';
import { css } from '@emotion/react';

const SomeComponent = ({ isLoading }) => {
  if (isLoading) return null;

  return (
    <div
      css={(euiThemeContext) => css`
        ${euiFontSize(euiThemeContext, 'l')}
        color: red;
      `
    />
  );
}

Please note, that if you encounter type errors with the theme parameter inside of the css function, you'll need to make your Plugin is set up to use Kibana's emotion.d.ts file.

To do this, add in the aforementioned emotion.d.ts with it's path relative to location of the typings directory as the value of the include property for the tsconfig.json file that exists within your plugin.

[cee-chen]

Theming and Emotion's css prop

Emotion's css prop allows consumers to receive the EUI theme from a callback within the prop:

<SomeComponent
  css={({ euiTheme }) => ({
    color: euiTheme.colors.primaryText,
    padding: euiTheme.size.l,
  })}
/>

This allows you to skip calling useEuiTheme() and is a nice syntactical sugar shortcut. That being said, there are caveats to its usage:

Typing

By default, Emotion's args for this API are untyped. You must define a theme in your own emotion.d.ts file for the above callback usage to be properly typed. You can simply extend EUI's theme like so:

import '@emotion/react';
import type { UseEuiTheme } from '@elastic/eui';

// @see https://emotion.sh/docs/typescript#define-a-theme
declare module '@emotion/react' {
  export interface Theme extends UseEuiTheme {}
}

You will then need to import this file into your tsconfig.json. See the osquery plugin for an example of their tsconfig setup.

Performance

Please note that the above callback syntax does come with performance implications, so if a high number of renders is an issue with the component you're styling, we recommend either defining your style callback statically outside the render cycle, or using useCallback to memoize your style fn. For example:

const YourStyles = ({ euiTheme }: UseEuiTheme) => ({
  color: euiTheme.colors.primary,
  padding: euiTheme.size.l,
});

export const YourComponent = () => (
  (<div css={YourStyles} />
);

[eokoneyo]

@cee-chen I merged in a PR here that makes it such that folks don't need to specifically add in a emotion.d.ts, it's handled globally now, for most folks if there's an existing include for the typings directory there would be no action to be done, it would just work as is. Other wise folks can add an include with the correct path to the one in the typings directory if they'd rather not include the entire directory.