in English

Theming Bootstrap

Fa'apitoa le Bootstrap 4 ma a tatou suiga fou Sass fa'apipi'iina mo le fa'avasegaina o sitaili fa'alelalolagi mo le fa'afaigofieina o autu ma suiga o vaega.

Folasaga

I le Bootstrap 3, o le autu na tele lava ina fa'auluina e suiga fesuisuiai i LESS, CSS masani, ma se isi sitaili autu na matou fa'aofiina i totonu oa matou distfaila. Faatasi ai ma se taumafaiga, e mafai e se tasi ona toe faʻafouina le foliga o Bootstrap 3 e aunoa ma le paʻi i faila autu. O le Bootstrap 4 o loʻo tuʻuina mai ai se masani, ae fai sina eseʻese auala.

Ole taimi nei, ole autu e ausia e Sass fesuiaiga, faʻafanua Sass, ma CSS masani. E leai se isi sitaili autu fa'apitoa; nai lo lena, e mafai ona e fa'atagaina le autu fausia e fa'aopoopo gradients, ata lafoia, ma isi mea.

Sass

Fa'aoga a matou faila Sass e fa'aoga lelei ai fesuiaiga, fa'afanua, fa'afefiloi, ma isi mea pe a fa'apipi'i Sass e fa'aoga ai lau lava paipa aseta.

Faiga faila

Soo se taimi e mafai ai, aloese mai le suia o faila autu a Bootstrap. Mo Sass, o lona uiga o le fatuina o lau lava sitaili e aumai ai le Bootstrap ina ia mafai ona e suia ma faʻalautele. Faʻapea o loʻo e faʻaaogaina se pule o pusa e pei o le npm, o le ai ai sau faila faila e pei o lenei:

your-project/
├── scss
│   └── custom.scss
└── node_modules/
    └── bootstrap
        ├── js
        └── scss

Afai na e siiina mai a matou faila faila ma e te le o faʻaaogaina se pule o pusa, e te manaʻo e setiina ma le lima se mea e tutusa ma lena fausaga, faʻapipiʻi ese faila a Bootstrap mai oe lava.

your-project/
├── scss
│   └── custom.scss
└── bootstrap/
    ├── js
    └── scss

Fa'aulufaleina mai

I lau custom.scss, e te fa'aulufaleina mai faila Sass puna a Bootstrap. E lua au filifiliga: aofia uma Bootstrap, pe filifili vaega e te manaʻomia. Matou te faʻamalosia le mulimuli, e ui ina ia nofouta e iai nisi o manaʻoga ma faʻalagolago i a matou vaega. E te manaʻomia foʻi le faʻaofiina o nisi JavaScript mo a matou plugins.

// Custom.scss
// Option A: Include all of Bootstrap

// Include any default variable overrides here (though functions won't be available)

@import "../node_modules/bootstrap/scss/bootstrap";

// Then add additional custom code here

// Custom.scss
// Option B: Include parts of Bootstrap

// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import "../node_modules/bootstrap/scss/functions";

// 2. Include any default variable overrides here

// 3. Include remainder of required Bootstrap stylesheets
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";

// 4. Include any optional Bootstrap components as you like
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/code";
@import "../node_modules/bootstrap/scss/grid";

Faatasi ai ma lena seti i le nofoaga, e mafai ona e amata suia soʻo se suiga o Sass ma faʻafanua i lau custom.scss. E mafai foi ona e amata faʻaopoopo vaega o Bootstrap i lalo o le // Optionalvaega pe a manaʻomia. Matou te fautua atu e fa'aaoga le fa'aputuga fa'aulufale atoa mai la matou bootstrap.scssfaila e fai ma ou amataga.

Fa'aletonu suiga

O fesuiaiga uma o Sass i Bootstrap e aofia ai le !defaultfuʻa e mafai ai ona e faʻamalo le tau le aoga o le fesuiaiga i lau lava Sass e aunoa ma le suia o le code source a Bootstrap. Kopi ma faapipii fesuiaiga pe a manaʻomia, sui o latou tau, ma aveese le !defaultfuʻa. Afai ua uma ona tuʻuina atu se fesuiaiga, o le a le toe tuʻuina atu e le tau faʻaletonu i Bootstrap.

O le ae mauaina le lisi atoa o fesuiaiga a Bootstrap i scss/_variables.scss. O nisi fesuiaiga e seti i le null, o nei fesuiaiga e le mafai ona faʻaalia le meatotino seʻi vagana ua faʻamalo i lau faʻatulagaga.

E tatau ona o'o mai suiga fesuia'i pe a mae'a ona fa'aulufaleina mai a tatou galuega, fesuiaiga, ma fefiloi, ae a'o le'i fa'aulufale mai.

O se faʻataʻitaʻiga lea e suia ai le background-colorma colormo le <body>taimi e faʻaulu mai ai ma tuʻufaʻatasia Bootstrap e ala ile npm:

@import "../node_modules/bootstrap/scss/functions";

// Default variable overrides
$body-bg: #000;
$body-color: #111;

// Required
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";

// Optional Bootstrap components here
@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

Toe fai pe a manaʻomia mo soʻo se fesuiaiga i Bootstrap, e aofia ai le lalolagi filifiliga o loʻo i lalo.

Amata i Bootstrap e ala i le npm ma la matou poloketi amata! Ulu i le twbs/bootstrap-npm-starter template repository e vaʻai pe faʻapefea ona fausia ma faʻavasega Bootstrap i lau lava galuega npm. E aofia ai Sass compiler, Autoprefixer, Stylelint, PurgeCSS, ma Bootstrap Icons.

Faafanua ma matasele

Bootstrap 4 o lo'o aofia ai nai fa'afanua Sass, pa'aga taua e fa'afaigofie ai ona fa'atupuina aiga o le CSS fa'atatau. Matou te fa'aogaina fa'afanua Sass mo a matou lanu, fa'asologa fa'asologa, ma isi mea. E pei lava o suiga a Sass, o fa'afanua Sass uma e aofia ai le !defaultfu'a ma e mafai ona fa'asili ma fa'alautele.

O nisi o matou fa'afanua Sass ua tu'ufa'atasia i fa'afanua gaogao ona o le fa'aletonu. E faia lea mea ina ia fa'afaigofie ai le fa'alauteleina o se fa'afanua Sass ua tu'uina atu, ae e sau i le tau o le aveesea o mea mai se fa'afanua e fai si faigata.

Suia faafanua

Ina ia suia se lanu o loʻo i ai i la matou $theme-colorsfaʻafanua, faʻaopoopo mea nei i lau faila masani Sass:

$theme-colors: (
  "primary": #0074d9,
  "danger": #ff4136
);

Faaopoopo i le faafanua

Ina ia fa'aopoopo se lanu fou i le $theme-colors, fa'aopoopo le ki fou ma le tau:

$theme-colors: (
  "custom-color": #900
);

Aveese mai faafanua

Ina ia aveese lanu mai le $theme-colors, poʻo soʻo se isi faʻafanua, faʻaaoga map-remove. Ia nofouta e tatau ona e tuʻuina i le va o matou manaʻoga ma filifiliga:

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";

$theme-colors: map-remove($theme-colors, "info", "light", "dark");

// Optional
@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
...

Manaomia ki

Bootstrap o loʻo faʻapea o loʻo iai ni ki faʻapitoa i totonu o faʻafanua Sass aʻo matou faʻaogaina ma faʻalauteleina i matou lava. A'o e fa'avasegaina fa'afanua o lo'o aofia ai, e te ono tula'i mai ni mea sese o lo'o fa'aogaina ai se ki fa'afanua patino a Sass.

Mo se fa'ata'ita'iga, matou te fa'aogaina le primary, success, ma dangerki mai $theme-colorsmo so'oga, fa'amau, ma fomu. O le suia o tulaga taua o nei ki e le tatau ona i ai ni faʻafitauli, ae o le aveeseina e ono mafua ai faʻafitauli Sass tuʻufaʻatasia. I nei tulaga, e te manaʻomia le suia o le Sass code e faʻaogaina ai na tulaga taua.

Galuega

E fa'aogaina e Bootstrap le tele o galuega a Sass, ae na'o se vaega itiiti e fa'aoga i le autu lautele. Ua matou aofia ai ni galuega se tolu mo le mauaina o tau mai fa'afanua lanu:

@function color($key: "blue") {
  @return map-get($colors, $key);
}

@function theme-color($key: "primary") {
  @return map-get($theme-colors, $key);
}

@function gray($key: "100") {
  @return map-get($grays, $key);
}

O nei mea e mafai ai ona e filifilia se lanu e tasi mai le faafanua Sass e pei o le auala e te faʻaogaina ai se lanu lanu mai le v3.

.custom-element {
  color: gray("100");
  background-color: theme-color("dark");
}

E iai fo'i se isi a matou galuega mo le mauaina o se tulaga fa'apitoa o lanu mai le $theme-colorsfa'afanua. O tulaga le lelei o le a faʻamalamalamaina le lanu, ae o le maualuga maualuga o le a pogisa.

@function theme-color-level($color-name: "primary", $level: 0) {
  $color: theme-color($color-name);
  $color-base: if($level > 0, #000, #fff);
  $level: abs($level);

  @return mix($color-base, $color, $level * $theme-color-interval);
}

I le fa'ata'ita'iga, e te vala'au le galuega ma pasi i ni ta'iala se lua: o le igoa o le lanu mai $theme-colors(fa'ata'ita'iga, muamua po'o le lamatiaga) ma le numera numera.

.custom-element {
  color: theme-color-level(primary, -10);
}

E mafai ona fa'aopoopo galuega fa'aopoopo i le lumana'i po'o lau lava Sass masani e fa'atupu ai ni galuega fa'aopoopo mo fa'afanua Sass fa'aopoopo, po'o se fa'afanua lautele pe a e mana'o e fa'asili atu lau tautala.

Fa'afeagai lanu

O se galuega faʻaopoopo matou te aofia ai i Bootstrap o le lanu faʻatusatusa galuega, color-yiq. E fa'aogaina le avanoa lanu YIQ e otometi ai ona toe fa'afo'i mai se moli ( #fff) po'o le pogisa ( #111) fa'atusatusa lanu e fa'atatau i le lanu fa'avae ua fa'amaonia. O lenei galuega e sili ona aoga mo faʻafefiloi poʻo faʻamau e te faʻatupuina ai le tele o vasega.

Mo se faʻataʻitaʻiga, ia faʻatupuina suʻega lanu mai la matou $theme-colorsfaʻafanua:

@each $color, $value in $theme-colors {
  .swatch-#{$color} {
    color: color-yiq($value);
  }
}

E mafai foʻi ona faʻaaogaina mo manaʻoga faʻatusatusa tasi:

.custom-element {
  color: color-yiq(#000); // returns `color: #fff`
}

E mafai foi ona e faʻamaonia se lanu faʻavae i la matou faʻafanua lanu galuega:

.custom-element {
  color: color-yiq(theme-color("dark")); // returns `color: #fff`
}

Sola SVG

Matou te fa'aogaina le escape-svggaluega e sola ese ai mai le <, >ma #mataitusi mo ata SVG pito i tua. O nei mataitusi e tatau ona sola ese ina ia faʻaalia lelei ata pito i tua ile IE. A fa'aogaina le escape-svggaluega, e tatau ona fa'ailoa mai fa'amaumauga URI.

Fa'aopoopo ma To'ese galuega

Matou te fa'aogaina le addma subtractgaluega e afifi ai le calcgaluega CSS. O le autu autu o nei galuega o le aloese mai mea sese pe a tuʻuina atu se tau "leai se tasi" 0i se calcfaʻamatalaga. O fa'amatalaga e pei o calc(10px - 0)le a toe fa'afo'i mai ai se mea sese i su'esu'ega uma, e ui lava e sa'o ile matematika.

Fa'ata'ita'iga o lo'o aoga le fa'atatau:

$border-radius: .25rem;
$border-width: 1px;

.element {
  // Output calc(.25rem - 1px) is valid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output the same calc(.25rem - 1px) as above
  border-radius: subtract($border-radius, $border-width);
}

Fa'ata'ita'iga pe a le aoga le calc:

$border-radius: .25rem;
$border-width: 0;

.element {
  // Output calc(.25rem - 0) is invalid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output .25rem
  border-radius: subtract($border-radius, $border-width);
}

Sass filifiliga

Fa'asinomaga Bootstrap 4 i la matou faila fa'aleaganu'u fa'aleaganu'u ma faigofie ona fesuia'i mana'oga CSS lalolagi ma suiga fou $enable-*Sass. Aveese le tau o se fesuiaiga ma toe tuufaatasia npm run testpe a manaʻomia.

E mafai ona e mauaina ma fa'avasega nei fesuiaiga mo filifiliga autu o le lalolagi i le scss/_variables.scssfaila a Bootstrap.

Fesuia'i Tulaga taua Fa'amatalaga
$spacer 1rem(valea), poʻo soʻo se tau> 0 Fa'amaoti mai le tau fa'aletonu e va'aia e fa'apolokalame ai a tatou mea fa'aoga spacer .
$enable-rounded true(valea) pefalse Fa'aagaaga border-radiussitaili mua'i fa'avasegaina i vaega eseese.
$enable-shadows truepo'o false(fa'aletonu) Fa'aagaaga box-shadowsitaili teuteu ua uma ona fa'avasega i vaega eseese. E le afaina box-shadows fa'aoga mo tulaga taula'i.
$enable-gradients truepo'o false(fa'aletonu) Fa'aagaaga gradients fa'avasegaina e ala i background-imagesitaili i vaega eseese.
$enable-transitions true(valea) pefalse Fa'aagaioi transitions fa'avasegaina i vaega eseese.
$enable-prefers-reduced-motion-media-query true(valea) pefalse Fa'aagaoioi le prefers-reduced-motionsu'esu'ega fa'asalalau , lea e taofiofia ai nisi fa'afiafiaga/sui fa'atatau ile su'esu'ega/fa'agaioiga faiga fa'apitoa a tagata fa'aoga.
$enable-hover-media-query truepo'o false(fa'aletonu) Ua le toe faaaogaina
$enable-grid-classes true(valea) pefalse Fa'aagaaga le fa'atupuina o vasega CSS mo le fa'atonuga (fa'ata'ita'iga, .container, .row, .col-md-1, etc.).
$enable-caret true(valea) pefalse Fa'aagaoioiga pseudo element caret on .dropdown-toggle.
$enable-pointer-cursor-for-buttons true(valea) pefalse Fa'aopoopo le "lima" cursor i elemene fa'amau e le fa'aletonu.
$enable-print-styles true(valea) pefalse Fa'atagaina sitaili mo le fa'asilisiliina o le lomitusi.
$enable-responsive-font-sizes truepo'o false(fa'aletonu) Fa'agaoioi le tele o mata'itusi tali .
$enable-validation-icons true(valea) pefalse Fa'aagaaga background-imageaikona i totonu o tusitusiga ma nisi fa'ailoga masani mo tulaga fa'amaonia.
$enable-deprecation-messages true(valea) pefalse Seti e falsenana lapataiga pe a faʻaaogaina soʻo se mea faʻafefiloi ma galuega faʻaletonu ua fuafua e aveese i totonu v5.

Lanu

O le tele o vaega eseese a Bootstrap ma mea aoga e fausia e ala i se faasologa o lanu o loʻo faʻamatalaina i se faʻafanua Sass. O lenei fa'afanua e mafai ona fa'apipi'iina i Sass e fa'atupu vave ai se faasologa o tulafono.

O lanu uma

O lanu uma o loʻo maua i le Bootstrap 4, o loʻo avanoa e pei o Sass fesuiaiga ma se faʻafanua Sass i scss/_variables.scssfaila. O lenei mea o le a faʻalauteleina i luga o faʻasalalauga laiti mulimuli ane e faʻaopoopo ai ata faʻaopoopo, e pei o le paleti grayscale ua uma ona matou faʻaofiina.

$ lanumoana #007bff
$ indigo #6610f2
$ viole #6f42c1
$ piniki #e83e8c
$mumu #dc3545
$ moli #fd7e14
$ samasama #ffc107
$meamata #28a745
$teal #20c997
$cyan #17a2b8

O le auala lenei e mafai ai ona e faʻaogaina nei mea i lau Sass:

// With variable
.alpha { color: $purple; }

// From the Sass map with our `color()` function
.beta { color: color("purple"); }

Color utility classes are also available for setting color and background-color.

In the future, we’ll aim to provide Sass maps and variables for shades of each color as we’ve done with the grayscale colors below.

Theme colors

We use a subset of all colors to create a smaller color palette for generating color schemes, also available as Sass variables and a Sass map in Bootstrap’s scss/_variables.scss file.

$primary #007bff
$secondary #6c757d
$success #28a745
$danger #dc3545
$warning #ffc107
$info #17a2b8
$light #f8f9fa
$dark #343a40

Grays

An expansive set of gray variables and a Sass map in scss/_variables.scss for consistent shades of gray across your project. Note that these are “cool grays”, which tend towards a subtle blue tone, rather than neutral grays.

$gray-100 #f8f9fa
$gray-200 #e9ecef
$gray-300 #dee2e6
$gray-400 #ced4da
$gray-500 #adb5bd
$gray-600 #6c757d
$gray-700 #495057
$gray-800 #343a40
$gray-900 #212529

Within scss/_variables.scss, you’ll find Bootstrap’s color variables and Sass map. Here’s an example of the $colors Sass map:

$colors: (
  "blue": $blue,
  "indigo": $indigo,
  "purple": $purple,
  "pink": $pink,
  "red": $red,
  "orange": $orange,
  "yellow": $yellow,
  "green": $green,
  "teal": $teal,
  "cyan": $cyan,
  "white": $white,
  "gray": $gray-600,
  "gray-dark": $gray-800
) !default;

Add, remove, or modify values within the map to update how they’re used in many other components. Unfortunately at this time, not every component utilizes this Sass map. Future updates will strive to improve upon this. Until then, plan on making use of the ${color} variables and this Sass map.

Components

Many of Bootstrap’s components and utilities are built with @each loops that iterate over a Sass map. This is especially helpful for generating variants of a component by our $theme-colors and creating responsive variants for each breakpoint. As you customize these Sass maps and recompile, you’ll automatically see your changes reflected in these loops.

Modifiers

Many of Bootstrap’s components are built with a base-modifier class approach. This means the bulk of the styling is contained to a base class (e.g., .btn) while style variations are confined to modifier classes (e.g., .btn-danger). These modifier classes are built from the $theme-colors map to make customizing the number and name of our modifier classes.

Here are two examples of how we loop over the $theme-colors map to generate modifiers to the .alert component and all our .bg-* background utilities.

// Generate alert modifier classes
@each $color, $value in $theme-colors {
  .alert-#{$color} {
    @include alert-variant(theme-color-level($color, -10), theme-color-level($color, -9), theme-color-level($color, 6));
  }
}

// Generate `.bg-*` color utilities
@each $color, $value in $theme-colors {
  @include bg-variant('.bg-#{$color}', $value);
}

Responsive

These Sass loops aren’t limited to color maps, either. You can also generate responsive variations of your components or utilities. Take for example our responsive text alignment utilities where we mix an @each loop for the $grid-breakpoints Sass map with a media query include.

@each $breakpoint in map-keys($grid-breakpoints) {
  @include media-breakpoint-up($breakpoint) {
    $infix: breakpoint-infix($breakpoint, $grid-breakpoints);

    .text#{$infix}-left   { text-align: left !important; }
    .text#{$infix}-right  { text-align: right !important; }
    .text#{$infix}-center { text-align: center !important; }
  }
}

Should you need to modify your $grid-breakpoints, your changes will apply to all the loops iterating over that map.

CSS variables

Bootstrap 4 includes around two dozen CSS custom properties (variables) in its compiled CSS. These provide easy access to commonly used values like our theme colors, breakpoints, and primary font stacks when working in your browser’s Inspector, a code sandbox, or general prototyping.

Available variables

Here are the variables we include (note that the :root is required). They’re located in our _root.scss file.

:root {
  --blue: #007bff;
  --indigo: #6610f2;
  --purple: #6f42c1;
  --pink: #e83e8c;
  --red: #dc3545;
  --orange: #fd7e14;
  --yellow: #ffc107;
  --green: #28a745;
  --teal: #20c997;
  --cyan: #17a2b8;
  --white: #fff;
  --gray: #6c757d;
  --gray-dark: #343a40;
  --primary: #007bff;
  --secondary: #6c757d;
  --success: #28a745;
  --info: #17a2b8;
  --warning: #ffc107;
  --danger: #dc3545;
  --light: #f8f9fa;
  --dark: #343a40;
  --breakpoint-xs: 0;
  --breakpoint-sm: 576px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 992px;
  --breakpoint-xl: 1200px;
  --font-family-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  --font-family-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}

Examples

CSS variables offer similar flexibility to Sass’s variables, but without the need for compilation before being served to the browser. For example, here we’re resetting our page’s font and link styles with CSS variables.

body {
  font: 1rem/1.5 var(--font-family-sans-serif);
}
a {
  color: var(--blue);
}

Breakpoint variables

A'o matou fa'auluina fa'amata'u i totonu o la matou fesuiaiga CSS (fa'ata'ita'iga, --breakpoint-md), e le'o lagolagoina i fesili fa'asalalau , ae e mafai lava ona fa'aoga i totonu o tulafono i fa'asalalauga fesili. O nei va'aiga va'aiga e tumau pea i le CSS tu'ufa'atasia mo feso'ota'iga i tua ona e mafai ona fa'aogaina e le JavaScript. Aoao atili i le spec .

O se fa'ata'ita'iga lea o mea e le'o lagolagoina:

@media (min-width: var(--breakpoint-sm)) {
  ...
}

Ma o se faʻataʻitaʻiga lea o mea e lagolagoina:

@media (min-width: 768px) {
  .custom-element {
    color: var(--primary);
  }
}