Sass guidelines
Core variables
Sizing
$euiSizeXS$euiSizeS$euiSizeM$euiSize$euiSizeL$euiSizeXL$euiSizeXXLZ-index
$euiZToastList$euiZComboBox$euiZModal$euiZMask$euiZNavigation$euiZContentMenu$euiZHeader$euiZContentColor
$euiColorEmptyShade$euiColorLightestShade$euiColorLightShade$euiColorMediumShade$euiColorDarkShade$euiColorDarkestShade$euiColorFullShade$euiColorPrimary$euiColorSecondary$euiColorAccent$euiColorDanger$euiColorWarning$euiColorSuccess$euiColorGhost$euiColorInkGoing beyond the provided colors
Theming patterns
Often you need to go beyond the provided color set. When doing so always use color functions to modify the base set. Here are some examples.
$euiCodeDangertint($euiCodeDanger, 30%)shade($euiCodeDanger, 30%)Remember that EUI provides dark and light mode theming support. Sometimes the traditional color functions don't give enough flexibility for both modes.
For example, depending upon what theme you use $EuiColorPrimary will be a different hex value.
$euiColorPrimaryis #0079A5 in the light theme
$euiColorPrimaryis #4da1c0 in the dark theme
Taking the default primary color above we want to tint the color in the light mode, but shade it in the dark mode. This makes the background color more subtle in both use cases.
// tintOrShade(color, tint_percent, shade_percent)
// will tint the color by % in light themes
// and shade the color by % in dark themes
.themedBox {
background-color: tintOrShade($euiColorPrimary, 90%, 70%);
border-left: $euiBorderThick;
border-color: $euiColorPrimary;
padding: $euiSize;
color: $euiTextColor;
}
Color contrast patterns
EUI provides some nifty color functions for auto-adjusting color to pass AA contrast checks. Often this is needed when using the base colors on top of each other. Here is an example similar to our callouts with a pesky orange.
// Make sure text passes a contrast check
.contrastBox {
$backgroundColor: tintOrShade($euiColorWarning, 90%, 70%);
background: $backgroundColor;
// Given two colors, adjust the first until contrast is 4.5
color: makeHighContrastColor($euiColorWarning, $backgroundColor);
padding: $euiSize;
border-left: $euiBorderThick;
border-color: $euiColorWarning;
}
More on color contrast
Consult the larger color guidelines page for a better explanation about passing color contrast.
Typography
View the variable and mixins Sass code for typography. For most of your components we recommend using EuiText or EuiTitle instead of these Sass variables.
@include euiFontSizeS;) to automatically apply line-height as well as size.Text sizes
$euiFontSizeXS$euiFontSizeS$euiFontSizeM$euiFontSize$euiFontSizeL$euiFontSizeXLText colors
$euiTextColor$euiColorDarkShade$euiLinkColorFont families
@include euiFont;@include euiCodeFont;Borders
EUI provides some helper variables for setting common border types.
border: $euiBorderThinborder: $euiBorderThickborder: $euiBorderEditableIn addition, you can utilize $euiBorderRadius to round the corners.
border: $euiBorderThin;
border-radius: $euiBorderRadius;
Shadow and Depth
Use mixins for shadows
@include euiSlightShadow;@include euiBottomShadowSmall;@include euiBottomShadowMedium;@include euiBottomShadowFlat;@include euiBottomShadow;@include euiBottomShadowLarge;Adding color to shadows
Most shadow mixins can also accept color.
@include euiBottomShadowLarge(desaturate($euiColorPrimary, 30%));Shadows to create graceful overflows
Primarily used in modals and flyouts, the overflow shadow masks the edges to indicate there is more content.
Vertical scrolling with euiYScrollWithShadows
It requires a wrapping element to control the height with overflow-y: hidden; and the content to@include euiYScrollWithShadows; or use the CSS utility class .eui-yScrollWithShadows.
Example:
.overflowY {
height: 200px;
overflow-y: hidden;
.overflowY__content {
@include euiYScrollWithShadows;
}
}Consequuntur atque nulla atque nemo tenetur numquam. Assumenda aspernatur qui aut sit. Aliquam doloribus iure sint id. Possimus dolor qui soluta cum id tempore ea illum. Facilis voluptatem aut aut ut similique ut. Sed repellendus commodi iure officiis exercitationem praesentium dolor. Ratione non ut nulla accusamus et. Optio laboriosam id incidunt. Ipsam voluptate ab quia necessitatibus sequi earum voluptate. Porro tempore et veritatis quo omnis. Eaque ut libero tempore sit placeat maxime laudantium. Mollitia tempore minus qui autem modi adipisci ad. Iste reprehenderit accusamus voluptatem velit. Quidem delectus eos veritatis et vitae et nisi. Doloribus ut corrupti voluptates qui exercitationem dolores.
Horizontal scrolling with euiXScrollWithShadows
You may want to add at least $euiSizeS's worth of padding to the sides of your content so the mask doesn't overlay it.
Example:
.overflowXContent {
@include euiXScrollWithShadows;
padding-left: $euiSizeS;
padding-right: $euiSizeS;
}Media queries and breakpoints
View the Sass code for media queries.
Breakpoints in EUI are provided through the use of a Sass mixin @include euiBreakpoint() that accepts an array of sizes.
Breakpoint sizing
xssmlxlMixin usage
Target mobile devices only
@include euiBreakpoint('xs','s') {...}Target mobile and tablets
@include euiBreakpoint('xs', 's', 'm') {...}Target tablets only
@include euiBreakpoint('m') {...}Target very wide displays only
@include euiBreakpoint('xl') {...}Animation
View the Sass code for animation.
EUI utilizes the following constants to maintain a similar 'bounce' to its animations. That said, animations are tricky, and if they aren't working for your specific application this is the one place where we think it's OK to come up with your own rules.
Speed
animation-duration: $euiAnimSpeedExtraFastanimation-duration: $euiAnimSpeedFastanimation-duration: $euiAnimSpeedNormalanimation-duration: $euiAnimSpeedSlowanimation-duration: $euiAnimSpeedExtraSlowTiming
animation-timing-function: $euiAnimSlightBounceanimation-timing-function: $euiAnimSlightResistanceSass best practices
Component based naming
EUI is written in a BEMish style with the addition of verb states (ex: *-isLoading). Below is an example of proper formatting.
// Use camelCase naming
.euiButton {
// Put mixins first before properties
@include euiButton;
@include euiSlightShadow;
border-radius: $euiBorderRadius;
// Elements exist within the component
.euiButton__content {
padding: 0 ($euiSize - $euiSizeXS);
}
// Modifiers augment existing components or elements
&.euiButton--primary {
background-color: $euiColorPrimary;
}
// States are written with a verb prefix
&.euiButton-isLoading {
opacity: .5;
}
}
// Put breakpoints at the bottom of the document
@include euiBreakpoint("xs", "s") {
.euiButton {
width: 100%;
}
}
Writing Sass the EUI way
In general, when writing new SCSS in a project that installs EUI as a dependency try to follow these best practices:
- Utilize color variables and functions rather than hard-coded values
- Utilize the sizing variables for padding and margins
- Utilize the animation variables for animations when possible
- Utilize the responsive mixins for all screen width calculations
- Utilize the typography mixins and variables for all font family, weight, and sizing
- Utilize the shadow mixins and z-index variables to manage depth
- Utilize the border and border-radius variable to handle border usage
- Minimize your overwrites and try to make new Sass additive in nature
Importing EUI global Sass
Most EUI based projects should already import the EUI global scope. For example, Kibana has its own liner that will give you everything on this page.
// In Kibana you can add this to the top of your Sass file
@import 'ui/public/styles/styling_constants';
If you want to construct your own import, you would just need to import the following core files into a fresh Sass project.
// In an outside project, import the core variables like so
@import '@elastic/eui/src/global_styling/functions/index';
@import '@elastic/eui/src/global_styling/variables/index';
@import '@elastic/eui/src/global_styling/mixins/index';