Migrating from Sass to Emotion
This page 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 Sizing tokens.
Sass | Emotion |
---|---|
$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:
euiTheme.base
returns a number (16 by default) that can have math performed on it, e.g:tsx code block:const width = `${useEuiTheme().euiTheme.base * 10}px`; // '160px'
- EUI offers a
mathWithUnits
utility that preserves the unit of the passed string. Example usage:tsx code block: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' }
- You can also prefer to use CSS's built-in
calc()
function, e.g.text code block:css` width: calc(${euiTheme.size.base} * 10); `
Colors
For a full list of tokens, see Color tokens.
Sass | Emotion |
---|---|
$euiColorPrimary /$euiColorSuccessText /etc | useEuiTheme().euiTheme.colors.primary / useEuiTheme().euiTheme.colors.successText (same lowercase naming scheme for all brand colors) |
$euiColorMediumShade /EmpyShade /etc |
|
$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 |
|
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:
tsx code block: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 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 Typography tokens.
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
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 Border tokens.
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
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 |