Sassのカスタマイズ（Sass）

ソースSassファイルを利用して、変数、マップ、ミックスイン、関数を活用して、プロジェクトをより迅速に構築とカスタマイズをする。

※"v5.2.0"での変更はv5.2.0-beta1での変更も含みます。
※"v5.3.0"での変更はv5.3.0-alpha版での変更も含みます。

このページの項目

ソースSassファイルを利用して、変数、マップ、ミックスインなどを活用。

ファイル構造（File structure）

できるだけBootstrapのコアファイルを変更しないで下さい。Sassの場合、独自のスタイルシートを作成してBootstrapをインポートして変更や拡張ができる。npmのようなパッケージマネージャーを使用しているなら、ファイル構造は次のようになる：

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

ソースファイルをダウンロードし、パッケージマネージャーを使用しない場合は、Bootstrapのソースファイルを自己のものとは別にして、その構造に似たものを手動で作成して下さい。

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

インポート（Importing）v5.3.0設定変更

custom.scss で、BootstrapのソースSassファイルをインポートするには、Bootstrap全部を組み込むか、必要な部分を選択するかの2つのオプションがある。Bootstrapプロジェクトチームとしては後者を推奨するが、Bootstrapのコンポーネント全体にはいくつかの要件と依存関係があるので注意。また、プラグイン用にいくつかのJavaScriptを組み込む必要がある。

Bootstrap5.3.0の設定例緑背景が5.2.0以降の変更箇所

custom.scss// オプションA: Bootstrapを全部組み込む

// ここにデフォルトの変数の再定義の設定を組み込む（関数は使用不可）

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

// ここにカスタムの設定を追加

custom.scss// オプションB: Bootstrapを部分的に組み込む

// 1. 最初に関数を組み込む（カラー、SVG、計算などが操作できるように）
@import "../node_modules/bootstrap/scss/functions";

// 2. ここにデフォルトの変数の再定義の設定を組み込む

// 3. 必須のBootstrapスタイルシートを組み込む（個別のカラーモードスタイルシートを含む）
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

// 4. ここにデフォルトのマップの再定義の設定を組み込む

// 5. 残りの必須のBootstrapスタイルシートを組み込む
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. 必要に応じて、オプションで他のパーツを組み込む
@import "../node_modules/bootstrap/scss/utilities";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/containers";
@import "../node_modules/bootstrap/scss/grid";
@import "../node_modules/bootstrap/scss/helpers";

// 7. 最後にオプションで、ユーティリティAPIを組み込んで、`_utilities.scss`のSassマップに基づいてクラスを生成
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. ここにカスタムの設定を追加

セットアップが整ったら、custom.scss のSass変数とマップの変更を開始。必要に応じてBootstrapの一部の追加もできる。開始点として、bootstrap.scss ファイルの完全なインポートスタックの使用を推奨。

【変更履歴】

【v5.0.0-beta3】（4.6.1でバックポート）
- オプションBの変数、ミックスインの設置場所：関数に続いてデフォルトの変数の再定義の前 ⇒ デフォルトの変数の再定義の後
【v5.1.0】
- オプションBの3.にrootが4.から移動（オプションから必須に）し、4.にユーティリティとヘルパーを追加し、5.にユーティリティAPIを追加し、6.がカスタムコードの設定に
【v5.2.0】
- オプションBの @import "../node_modules/bootstrap/scss/variables"; の後ろに4.としてデフォルトのマップの再定義の設定場所を追加（その後の必須のスタイルシートを5.に、オプションを4.から6.に、ユーティリティAPIを5.から7.に、カスタムコードを6.から８.に変更）
- スタイルシートのSassからカラーシステムのマップを切り離したオプションBの5.に @import "../node_modules/bootstrap/scss/maps"; を追加
【v5.3.0】
- オプションBの3.に @import "../node_modules/bootstrap/scss/variables-dark";（ダークモードの設定）を追加

コンパイル（Compiling）v5.3.1追加

カスタムSassコードをブラウザでCSSとして使用するためにはSassコンパイラが必要。SassはCLIパッケージとして出荷されているが、GulpやWebpackなどのビルドツールやGUIアプリケーションでコンパイルすることもできる。またIDEによってはSassコンパイラが組み込まれていたり、ダウンロード可能な拡張機能として用意されているものもある。

一般にはSassのコンパイルにはCLIを使用することが好まれるが、自分が好きな方法を使用できる。コマンドラインから以下を実行：

# Install Sass globally
npm install -g sass

# Watch your custom Sass for changes and compile it to CSS
sass --watch ./scss/custom.scss ./css/custom.css

オプションの詳細については、sass-lang.com/installとVS Codeでコンパイルを参照して下さい。

Bootstrapを他のビルドツールで使用する場合は、Webpack、Parcel、Viteでコンパイルするためのガイドを読んで下さい。またGitHubのexamplesリポジトリには、本番環境で使用できるデモを用意。

組み込み（Including）v5.3.1追加

CSSがコンパイルされたら、HTMLファイルに組み込むことができる。index.html の中にコンパイルしたCSSファイルを記述して下さい。コンパイルしたCSSファイルのパスを変更した場合は、必ず更新して下さい。

設定例

<!doctype html>
<html lang="ja">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>カスタムBootstrap</title>
    <link href="/css/custom.css" rel="stylesheet">
  </head>
  <body>
    <h1>ようこそ!</h1>
  </body>
</html>

変数のデフォルト値（Variable defaults）v5.3.0設定変更

BootstrapのすべてのSass変数には!default フラグが含まれており、Bootstrapのソースコードを変更せずに、独自のSassで変数のデフォルト値を再定義できる。必要に応じて変数をコピーして貼り付け、その値を変更して !default フラグを削除する。変数がすでに割り当てられている場合は、Bootstrapのデフォルト値によって再割り当てされることはない。

Bootstrapの変数の完全なリストは scss/_variables.scss にある。一部の変数は null に設定されており、これらの変数は任意に再定義されない限りプロパティを出力しない。

変数の再定義は、関数がインポートされた後、残りのインポートの前に行われる必要がある。

Bootstrapをnpm経由で読み込んでコンパイルするときに <body> の background-color と color を変更するには、次のようにする：

Bootstrap5.3.0の設定例緑背景が5.2.0以降の変更箇所

custom.scss// 必須
@import "../node_modules/bootstrap/scss/functions";

// デフォルトの変数の再定義
$body-bg: #000;
$body-color: #111;

// 必須
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// オプションのBootstrapコンポーネント
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// など

以下のグローバルオプションを含め、Bootstrapの変数に対して必要に応じて繰り返す。

【変更履歴】

【v5.0.0-beta2】（v4.6.0でバックポート）
- デフォルトの変数の再定義の設置場所：Bootstrapとそのデフォルト変数の前か後 ⇒ 関数、変数、ミックスインがインポートされた後、残りのインポートの前
【v5.0.0-beta3】（4.6.1でバックポート）
- 変数、ミックスインの設置場所：関数に続いてデフォルトの変数の再定義の前 ⇒ デフォルトの変数の再定義の後
【v5.1.0】
- rootがオプションから必須に移動
【v5.2.0】
- scss/_maps.scss を新設したので、必須にインポートするSassファイルに bootstrap/scss/maps を追加
【v5.3.0】
- カラーモードの新設に伴い、必須にインポートするSassファイルに bootstrap/scss/variables-dark（ダークモードの変数）を追加

マップとループ（Maps and loops）v5.0.0-alpha1設定変更

Bootstrap5には、関連するCSSのグループを簡単に生成できるにするキーと値のペアであるSassマップがいくつか組み込まれている。カラー、グリッドのブレークポイントなどにSassマップを使用。Sass変数と同様に、すべてのSassマップには !default フラグが含まれており、再定義や拡張ができる。

Bootstrap5から、v4 にあったマップのマージを破棄した。この方法で不要な値の削除がより詳細に制御できる。

【変更履歴】

【v5.0.0-alpha1】
- $grays（グレースケール変数）, $colors（カラー変数）, $theme-colors（テーマカラー変数）, $spacers（空白値変数）, $embed-responsive-aspect-ratios（埋込動画のアスペクト比変数）, $form-validation-states（フォームの検証状態変数）の各変数から map-merge を削除
【v5.2.0】
- scss/_maps.scss を新設し、以下のマップ変数を scss/_variables.scss から移動（元のマップへの更新が拡張するセカンダリマップに適用されない問題を修正するため）
  - $theme-colors-rgb（テーマカラーのRGB）
  - $utilities-colors
  - $utilities-text, $utilities-text-colors（文字色ユーティリティの不透明度）
  - $utilities-bg, $utilities-bg-colors（背景色ユーティリティの不透明度）
  - $negative-spacers（マイナスのマージン）
  - $gutters（ガター）

マップを変更（Modify map）

$theme-colors マップ内のすべての変数は独立した変数として定義されている。Bootstrapの $theme-colors マップの既存のカラーを変更するには、任意のSassファイルに以下を追加：

Bootstrap5.xの設定例緑背景が変更箇所

custom.scss$primary: #0074d9;
$danger: #ff4136;

後で、これらの変数をBootstrapの $theme-colors マップに設定。

設定例

custom.scss$theme-colors: (
  "primary": $primary,
  "danger": $danger,
  ...
);

※Bootstrap4.xの設定例赤背景が変更箇所

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

【変更履歴】

【v5.0.0-alpha1】
- $theme-colors マップにカラーを設定する場合、一旦 ${color} 変数を設定して、$theme-colors マップに ${color} 変数を設定

マップに追加（Add to map）v5.0.0-alpha2設定変更

$theme-colors やその他のマップに新しい色を追加するには、カスタム値を使用して新しいSassマップを作成し、元のマップとマージする。この場合、新しい $custom-colors マップを作成し、それを $theme-colors とマージする。

Bootstrap5.xの設定例緑背景が変更箇所

custom.scss// 独自のマップを作成
$custom-colors: (
  "custom-color": #900
);

// マップをマージ
$theme-colors: map-merge($theme-colors, $custom-colors);

※Bootstrap4.xの設定例赤背景が変更箇所

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

【設定】

$theme-colors マップにカラーを追加する場合、一旦カスタムカラーの変数（$custom-colors）を設定して、$theme-colors マップの既存のカラー設定をマージ

【変更履歴】

【v5.0.0-alpha2】
- $theme-colors マップにカラーを追加する場合は、一旦カスタムカラーの変数を設定する必要あり

マップから削除（Remove from map）v5.2.0設定変更

$theme-colors やその他のマップから色を削除するには、map-remove を使用し、必須の variables で定義した直後と maps で使用する前に、$theme-colors を挿入する必要があるので注意。

Bootstrap5.2.0～の設定例緑背景が5.2.0での変更箇所

custom.scss// 必須
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";

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

@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";
// オプション
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// など

【変更履歴】

【v5.1.0】
- rootがオプションから必須に移動
【v5.2.0】
- scss/_maps.scss を新設したので、必須にインポートするSassファイルに bootstrap/scss/maps を追加
- $theme-colors の位置：オプションの手前から、必須の variables と maps の間に変更

必須キー（Required keys）

Bootstrapでは、Sassマップ内に特定のキーがあることを想定しており、これらを使用して拡張している。組み込み済のマップをカスタマイズすると、特定のSassマップのキーが使用されているときにエラーが発生することがある。

例えば、リンク、ボタン、フォームの状態には、$theme-colors の primary, success, danger のキーを使用。これらのキーの値を置き換えても問題はないが、削除するとSassコンパイルの問題が発生する可能性がある。この場合、これらの値を使用するSassコードを変更する必要がある。

関数（Functions）

カラー（Colors）v5.0.0-beta1設定変更

Bootstrapが持つSassマップの次に、テーマの色を $primary のように単独の変数として使用できる。

Bootstrap5.xの設定例緑背景が変更箇所

custom.scss.custom-element {
  color: $gray-100;
  background-color: $dark;
}

※Bootstrap4.xの設定例赤背景が変更箇所

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

Bootstrapの tint-color() 関数と shade-color() 関数を使用すれば、色に明暗をつけられる。これらの関数は、従来あったSassの lighten() と darken() 関数とは異なり、色を黒か白と混合する。それらは明度を一定量変更するのだが、多くの場合、目的の効果が得られないため。

shift-color() は、ウエイトが正の場合は色に明暗を付け、負の場合は色を着色することで、これら2つの関数を組み合わせる。

Bootstrap5.xの設定

scss/_functions.scss 内 color-functions の設定// 色合い：色と白を混ぜる
@function tint-color($color, $weight) {
  @return mix(white, $color, $weight);
}

// 色に明暗をつける：色と黒を混ぜる
@function shade-color($color, $weight) {
  @return mix(black, $color, $weight);
}

// 色をスケールする：
// ウエイトが正の場合は色に明暗を付け、そうでない場合は色を付ける。
@function shift-color($color, $weight) {
  @return if($weight > 0, shade-color($color, $weight), tint-color($color, -$weight));
}

※Bootstrap4.xの設定

scss/_functions.scss 内 Request a theme color level の設定@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);
}

実際には、関数を呼び出して、色と重みのパラメータを渡す。

Bootstrap5.xの設定例緑背景が変更箇所

custom.scss.custom-element {
  color: tint-color($primary, 10%);
}

.custom-element-2 {
  color: shade-color($danger, 30%);
}

.custom-element-3 {
  color: shift-color($success, 40%);
  background-color: shift-color($success, -60%);
}

※Bootstrap4.xの設定例赤背景が変更箇所

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

【変更履歴】

【v5.0.0-alpha1】
- color(), theme-color(), gray() 関数を廃止（値が単独の変数としても利用できるため）
- theme-color() や theme-color-level() 関数の設定では、直接 ${color} 変数を使用
【v5.0.0-alpha3】
- color-level(), lighten(), darken() の各関数と $level, $theme-color-interval の各変数などを廃止し、tint-color(), shade-color(), scale-color() の各関数と $weight 変数などを使用
【v5.0.0-beta1】
- Sass独自のカラースケーリング関数との衝突を避けるため、scale-color() 関数の名前を shift-color() に変更

カラーコントラスト（Color contrast）v5.0.0-alpha1設定変更

Web Content Accessibility Guidelines (WCAG)のコントラスト要件を満たすために、サイト作成者は、ごくわずかな例外を除いて、最小4.5：1のテキストカラーコントラストと最小3：1の非テキストカラーコントラストを提供する必要がある。

これを支援するために、Bootstrapに color-contrast 関数を組み込んだ。WCAGコントラスト比アルゴリズムを使用して、sRGB 色空間の相対輝度に基づいて限界明暗比を計算し、指定されたベースカラーに基づいてlight（#fff）, dark（#212529）, black（#000）コントラストカラーを自動的に返す。この関数は、複数のクラスを生成するミックスインやループで特に役立つ。

例えば、$theme-colors マップからカラースウォッチ（色見本）を生成するには：

設定例

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

また、1回限りのコントラストのニーズにも使用できる：

設定例

custom.scss.custom-element {
  color: color-contrast(#000); // `color: #fff` を返す
}

カラーマップ関数でベースカラーの指定もできる：

Bootstrap5.xの設定例緑背景が変更箇所

custom.scss.custom-element {
  color: color-contrast($dark); // `color: #fff` を返す
}

※Bootstrap4.xの設定例赤背景が変更箇所

custom.scss.custom-element {
  color: color-yiq(theme-color("dark")); // `color: #fff` を返す
}

【変更履歴】

【v5.0.0-alpha1】
- 使用する関数：color-yiq ⇒ color-contrast
- テーマカラーを使用する場合：color-yiq(theme-color("{color}")) ⇒ color-contrast(${color})

SVGからのエスケープ（Escape SVG）

SVG背景画像の <, >, # の各文字をエスケープするのに escape-svg 関数を使用。escape-svg 関数を使用する場合、データURIを引用符で囲む必要がある。

AddとSubtract関数（Add and Subtract functions）

Bootstrapでは、CSSの calc 関数で包括させるために、add（加算）と subtract（減算）関数を使用。これらの関数の主な使用目的は、calc の式で「ユニットレス」の 0 値が指定された場合のエラーを回避するため。calc(10px - 0) のような式は数学的には正しいのだが、すべてのブラウザでエラーが返されてしまう。

calcが有効な例：

設定例

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

.element {
  // calc(.25rem - 1px) の出力は有効
  border-radius: calc($border-radius - $border-width);
}

.element {
  // 上記と同じ calc(.25rem - 1px) を出力
  border-radius: subtract($border-radius, $border-width);
}

calcが無効な例：

設定例

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

.element {
  // calc(.25rem - 0) の出力は無効
  border-radius: calc($border-radius - $border-width);
}

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

ミックスイン（Mixins）v5.0.0追加

scss/mixins/ ディレクトリには、Bootstrapの一部を強化する大量のミックスインがあり、独自のプロジェクト全体でも使用できる。

配色（Color schemes）

prefers-color-scheme メディアクエリの省略形ミックスインは、light と dark の配色をサポート。カラーモードミックスインの情報は、カラーモードの解説に記載。

デフォルトの設定

scss/mixins/_color-scheme.scss 内 mixin-color-scheme の設定@mixin color-scheme($name) {
  @media (prefers-color-scheme: #{$name}) {
    @content;
  }
}

設定例

custom.scss.custom-element {
  @include color-scheme(light) {
    // ここにライトモードスタイルを挿入
  }
  @include color-scheme(dark) {
    // ここにダークモードスタイルを挿入
  }
}

前のページ
カスタマイズの概要

次のページ
Sass オプション

Sassのカスタマイズ（Sass）

ファイル構造（File structure）

インポート（Importing）v5.3.0設定変更

Bootstrap5.3.0の設定例 緑背景が5.2.0以降の変更箇所

【変更履歴】

コンパイル（Compiling）v5.3.1追加

組み込み（Including）v5.3.1追加

設定例

変数のデフォルト値（Variable defaults）v5.3.0設定変更

Bootstrap5.3.0の設定例 緑背景が5.2.0以降の変更箇所

【変更履歴】

マップとループ（Maps and loops）v5.0.0-alpha1設定変更

【変更履歴】

マップを変更（Modify map）

Bootstrap5.xの設定例 緑背景が変更箇所

設定例

※Bootstrap4.xの設定例 赤背景が変更箇所

【変更履歴】

マップに追加（Add to map）v5.0.0-alpha2設定変更

Bootstrap5.xの設定例 緑背景が変更箇所

※Bootstrap4.xの設定例 赤背景が変更箇所

【設定】

【変更履歴】

マップから削除（Remove from map）v5.2.0設定変更

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所

【変更履歴】

必須キー（Required keys）

関数（Functions）

カラー（Colors）v5.0.0-beta1設定変更

Bootstrap5.xの設定例 緑背景が変更箇所

※Bootstrap4.xの設定例 赤背景が変更箇所

Bootstrap5.xの設定

※Bootstrap4.xの設定

Bootstrap5.xの設定例 緑背景が変更箇所

※Bootstrap4.xの設定例 赤背景が変更箇所

【変更履歴】

カラーコントラスト（Color contrast）v5.0.0-alpha1設定変更

設定例

設定例

Bootstrap5.xの設定例 緑背景が変更箇所

※Bootstrap4.xの設定例 赤背景が変更箇所

【変更履歴】

SVGからのエスケープ（Escape SVG）

AddとSubtract関数（Add and Subtract functions）

設定例

設定例

ミックスイン（Mixins）v5.0.0追加

配色（Color schemes）

デフォルトの設定

設定例

ページ移動

Bootstrap5.3.0の設定例緑背景が5.2.0以降の変更箇所

Bootstrap5.3.0の設定例緑背景が5.2.0以降の変更箇所

Bootstrap5.xの設定例緑背景が変更箇所

※Bootstrap4.xの設定例赤背景が変更箇所

Bootstrap5.xの設定例緑背景が変更箇所

※Bootstrap4.xの設定例赤背景が変更箇所

Bootstrap5.2.0～の設定例緑背景が5.2.0での変更箇所

Bootstrap5.xの設定例緑背景が変更箇所

※Bootstrap4.xの設定例赤背景が変更箇所

Bootstrap5.xの設定例緑背景が変更箇所

※Bootstrap4.xの設定例赤背景が変更箇所

Bootstrap5.xの設定例緑背景が変更箇所

※Bootstrap4.xの設定例赤背景が変更箇所