メインコンテンツにスキップ ドキュメントナビゲーションにスキップ

JavaScript v5.2.0更新

オプションのJavaScriptプラグインを使用してBootstrapを有効にする。各プラグイン、データおよびプログラムAPIオプションなどについて学習する。

※"v5.0.0"での変更はv5.0.0-alpha版、v5.0.0-beta版での変更も含みます。

※"v5.2.0"での変更はv5.2.0-beta1での変更も含みます。
※"v5.3.0"での変更はv5.3.0-alpha版での変更も含みます。
このページの項目 v5.2.0更新

個別か一括で（Individual or compiled）

プラグインは個別ファイル（Bootstrapの個別の /js/dist/*.js ファイルを使用）か、一括ファイル（bootstrap.js か軽量版の bootstrap.min.js）が使用できる（両方を組み込む必要はない）。

バンドラ（webpack、Parcel、Viteなど）を使用する場合は、UMD対応の /js/dist/*.js ファイルが使用できる。

※Bootstrapの個別の *.js ファイル（ソースファイルの js/dist/ 内にある）

【変更履歴】
  • 【v5.0.0-alpha1】
    • index.js（webpackなどに組込用）は、ソースファイル内の js/index.esm.js や js/index.umd.js に移動
    • util.js（ユーティリティ用）は、ソースファイル内の js/src/util/index.js に移動
  • 【v5.0.0-bata2】
    • base-component.js を新設
  • 【v5.0.0-bata3】

JavaScriptフレームワークでの使用（Usage with JavaScript frameworks）v5.2.0新設

BootstrapのCSSはどのフレームワークでも使用できるが、BootstrapのJavaScriptは、DOMの完全な知識を前提とするReact、Vue、AngularなどのJavaScriptフレームワークとは完全な互換性はない。Bootstrapとフレームワークの両方が同じDOM要素を変更しようとする可能性があり、その結果ドロップダウンなどのバグが"オープン"な位置で積み重なる。

このタイプのフレームワークを使用している場合のより良い代替手段は、BootstrapのJavaScriptの代わりにフレームワーク固有のパッケージをご使用下さい。以下に最も人気のあるオプションのいくつかを表示。

モジュールとしてのBootstrapの使い方（Using Bootstrap as a module）v5.0.0-alpha1新設、v5.2.0更新

<script type="module"> がターゲットのブラウザでサポートされている場合、Bootstrapをブラウザのモジュールとして使用できるようにするために、ESM（ES Modules）で構築されたBootstrapのバージョン（bootstrap.esm.js と bootstrap.esm.min.js）を提供。

設定例
<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

JSバンドラと比較して、ブラウザでESMを使用するには、モジュール名の代わりにフルパスとファイル名を使用する必要がある。詳細は、V8のJavaScript modulesに記載。そのため、上記では 'bootstrap' の代わりに 'bootstrap.esm.min.js' を使用。ただし、これは、次のようにPopperをJavaScriptにインポートする場合は、Popperの依存関係によってさらに複雑になる：

import * as Popper from "@popperjs/core"

これをそのまま試すと、コンソールに次のようなエラーが表示される：

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

これを修正するには、importmap を使用して任意のモジュール名を解決し、パスを完成させる。importmap をターゲットのブラウザがサポートしていない場合は、es-module-shimsプロジェクトを使用する必要がある。BootstrapとPopperでどのように機能するかを以下に示す。

Bootstrap5.3.0の設定例 緑背景が5.3.0での変更箇所
<!doctype html>
<html lang="ja">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
    <title>ハロ－、モジュラリティ!</title>
  </head>
  <body>
    <h1>ハロ－、モジュラリティ!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" data-bs-toggle="popover" title="ブラウザのESM" data-bs-content="Bang!">カスタム popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.8/dist/esm/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>
【変更履歴】
  • 【v5.3.0】
    • Boottrapをモジュールとして使用する場合は "@popperjs/core" はESM Popper CDNリファレンスを使用

依存関係（Dependencies）v5.0.0-alpha1変更

一部のプラグインとCSSコンポーネントは、他のプラグインに依存する。個別のプラグインを組み込む場合は、解説でこれらの依存関係をご確認下さい。

Bootstrapのドロップダウン、ツールチップ、ポップオーバーは、Popperにも依存している。

【変更履歴】
  • 【v5.0.0-alpha1】
    • すべてのプラグインにおいてjQueryとの依存関係が必要なくなった

データ属性（Data attributes）v5.2.0更新

ほぼ全てのBootstrapプラグインは、HTMLだけでデータ属性を使用して有効化と構成ができる（JavaScript機能を使用する推奨方法）。必ず1つの要素に対して1組のデータ属性をご使用下さい（例：同じボタンからツールチップとモーダルを起動することはできない）。

オプションは、データ属性かJavaScriptを経由して渡すことができるため、data-bs-animation="{value}" のように、オプション名を data-bs- に追加できる。データ属性を経由してオプションを渡す場合は、必ずオプション名の命名規則をキャメルケース（単語の先頭を大文字にする）からケバブケース（単語をハイフンでつなぐ）にご変更下さい。例：data-bs-customClass="beautifier" ではなく、data-bs-custom-class="beautifier" を使用する。

Bootstrap 5.2.0以降、すべてのコンポーネントは、JSON文字列として単純なコンポーネント構成を格納できる実験的な予約済データ属性 data-bs-config をサポート。要素に data-bs-config='{"delay":0, "title":123}' と data-bs-title="456" 属性がある場合、最終的な title 値は 456 になり、個別のデータ属性は data-bs-config で指定された値を再定義する。さらに、既存のデータ属性には、data-bs-delay='{"show":0,"hide":150}' のようなJSON値を格納できる。

【変更履歴】
  • 【v5.0.0-alpha1】
    • データ属性APIの無効と data-api の名前空間とともに名前空間としてプラグインの名前を組み込む方法は削除

セレクタ（Selectors）v5.2.0注意書きから更新

パフォーマンス上の理由から、ネイティブの querySelector メソッドと querySelectorAll メソッドを使用してDOM要素をクエリするため、有効なセレクタを使用する必要がある。collapse:Example のような特殊なセレクタを使用する場合は、必ずそれらをエスケープして下さい。

イベント（Events）v5.3.1設定変更

Bootstrapは、ほとんどのプラグインの独自の動作のためのカスタムイベントを提供。通常、これらは動詞、過去分詞の形態になる－動詞形（show など）がイベントの開始時に起動され、その過去分詞形（shown など）がアクションの完了時に起動される。

すべての動詞形のイベントで preventDefault() 機能を提供。これにより、アクション開始前にそのアクションの実行を停止できる。イベントハンドラからfalseを返すと、preventDefault() も自動的に呼び出される。

Bootstrap5.3.1～の設定例 緑背景が5.2.0以降の変更箇所
JavaScriptconst myModal = document.querySelector('#myModal')

myModal.addEventListener('show.bs.modal', event => {
  return event.preventDefault() // モーダルの表示を止める
})
※Bootstrap5.1.xの設定例 赤背景が5.2.0以降の変更箇所
JavaScriptvar myModal = document.getElementById('myModal')

myModal.addEventListener('show.bs.modal', function (event) {
  if (!data) {
    return event.preventDefault()
  }
})
※Bootstrap4.xの設定例
JavaScript$('#myModal').on('show.bs.modal', function (event) {
  if (!data) {
    return event.preventDefault()
  }
})
【変更履歴】
  • 【v5.2.0】
    • JavaScriptの記述
      • ES6(ES2015)に変更
      • document.getElementById('ID') ⇒ document.querySelector('#ID')
  • 【v5.3.1】
    • if (!data) {} を削除

プログラムに基づいたAPI（Programmatic API）v5.2.0設定変更

すべてのコンストラクタはオプションのoptionsオブジェクトを受け入れるか、または何も受け入れない（これによりデフォルトの動作でプラグインが起動される）。

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst myModalEl = document.querySelector('#myModal')
const modal = new bootstrap.Modal(myModalEl) // デフォルトで初期化

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // キーボードなしで初期化
※Bootstrap5.1.xの設定例 赤背景が5.2.0での変更箇所
JavaScriptvar myModalEl = document.getElementById('myModal')
var modal = new bootstrap.Modal(myModalEl)

var modal = new bootstrap.Modal(myModalEl, { keyboard: false })
※Bootstrap4.xの設定例
JavaScript$('#myModal').modal()
$('#myModal').modal({ keyboard: false })

特定のプラグイン・インスタンスを取得する場合、各プラグインは getInstance メソッドを公開する。例えば、要素から直接インスタンスを取得するには、次のようにする：

Bootstrap5.xの設定例 緑背景が変更箇所
JavaScriptbootstrap.Popover.getInstance(myPopoverEl)
※Bootstrap4.xの設定例
JavaScript$('[rel=popover]').data('popover')

インスタンスが要求された要素に対して開始されていない場合、このメソッドは null を返す。

または、getOrCreateInstance を使用して、DOM要素に関連付けられたインスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる。

設定例
JavaScriptbootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

インスタンスが初期化されていない場合は、オプションの構成オブジェクトを受け入れて2番目の引数として使用できる。

【変更履歴】
  • 【v5.2.0】
    • JavaScriptの記述
      • ES6(ES2015)に変更
      • document.getElementById('ID') ⇒ document.querySelector('#ID')

コンストラクタのCSSセレクタ（CSS selectors in constructors）v5.0.0-beta3追加

getInstance メソッドと getOrCreateInstance メソッドに加えて、すべてのプラグインコンストラクタは、最初の引数としてDOM要素か有効なCSSセレクタを受け入れることができる。プラグインは単一の要素のみをサポートするため、プラグイン要素は querySelector メソッドで検出される。

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')
※Bootstrap5.1.xの設定例 赤背景が5.2.0での変更箇所
var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
var offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
var alert = bootstrap.Alert.getOrCreateInstance('#myAlert')
【変更履歴】
  • 【v5.2.0】
    • JavaScriptの記述をES6(ES2015)に変更

同期関数と遷移（Asynchronous functions and transitions）

すべてのプログラムAPIメソッドは非同期であり、遷移が開始された後、終了する前に呼び出し元に戻る。

遷移が完了したらアクションを実行するために、対応するイベントに従う。

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // 折り畳み領域が展開された後に実行するアクション
})
※Bootstrap5.1.xの設定例 赤背景が5.2.0での変更箇所
JavaScriptvar myCollapseEl = document.getElementById('myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', function (event) {
  // 折り畳み領域が展開された後に実行するアクション
})
※Bootstrap4.xの設定例
JavaScript$('#myCollapse').on('shown.bs.collapse', function (event) {
  // 折り畳み領域が展開された後に実行するアクション
})

さらに、遷移コンポーネントのメソッド呼び出しは無視される。

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // カルーセル・インスタンスを取得

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // スライド1への移行が終了するとすぐにスライド2にスライド
})

carousel.to('1') // スライド1にスライドして呼び出し元に戻る
carousel.to('2') // !! スライド1への移行が終了していないため、無視される !!
※Bootstrap5.1.xの設定例 赤背景が5.2.0での変更箇所
JavaScriptvar myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl)

myCarouselEl.addEventListener('slid.bs.carousel', function (event) {
  carousel.to('2')
})

carousel.to('1')
carousel.to('2')
※Bootstrap4.xの設定例
JavaScript$('#myCarousel').on('slid.bs.carousel', function (event) {
  $('#myCarousel').carousel('2')
})

$('#myCarousel').carousel('1')
$('#myCarousel').carousel('2')
【変更履歴】
  • 【v5.2.0】
    • JavaScriptの記述
      • ES6(ES2015)に変更
      • document.getElementById('ID') ⇒ document.querySelector('#ID')

dispose メソッド（dispose method）v5.2.0新設

hide() の直後に dispose メソッドを使用するのは正しいように見えるかもしれないが、誤った結果になる。問題のある使用例を以下に示す。

設定例
JavaScriptconst myModal = document.querySelector('#myModal')
myModal.hide() // 非同期

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

デフォルト設定（Default settings）

プラグインの Default オブジェクトを変更することにより、プラグインのデフォルト設定を変更できる：

Bootstrap5.xの設定例 緑背景が変更箇所
JavaScript// モーダルプラグインの`keyboard`オプションのデフォルトをfalseに変更
bootstrap.Modal.Default.keyboard = false
※Bootstrap4.xの設定例 赤背景が変更箇所
JavaScript$.fn.modal.Constructor.DEFAULTS.keyboard = false

メソッドとプロパティ（Methods and properties）v5.2.0新設

すべてのBootstrapプラグインは、以下のメソッドと静的プロパティを公開。

メソッド 説明
dispose 要素のコンポーネントを破棄（DOM要素に保存されているデータを削除）。
getInstance DOM要素に関連付けられたコンポーネント・インスタンスを取得できる静的メソッド。
getOrCreateInstance DOM要素に関連付けられたコンポーネント・インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成したりできる静的メソッド。
静的プロパティ 説明
NAME プラグイン名を返す。（例：bootstrap.Tooltip.NAME）
VERSION Bootstrapの各プラグインのバージョンには、プラグインのコンストラクタの VERSION プロパティを経由してアクセスできる。（例：bootstrap.Tooltip.VERSION）

HTMLサニタイザー（Sanitizer）v5.0.0-alpha2名称変更

ツールチップとポップオーバーでは、HTMLを受け付けるオプションでサニタイズするためにBootstrap内蔵のサニタイザーを使用。
※ツールチップとポップオーバープラグインの data-bs-template 属性には、属性値に渡されるHTMLの適切なXSSサニタイズがなかったため実装。

デフォルトの allowList 値は次のとおり：v5.3.3更新

JavaScriptconst ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i

const DefaultAllowlist = {
  // 以下の任意の要素で許可されているグローバル属性
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  dd: [],
  div: [],
  dl: [],
  dt: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'srcset', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

このデフォルトの allowList に新しい値を追加したい場合は、次のようにする：

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// テーブル要素を許可
myDefaultAllowList.table = []

// td要素とtd要素のdata-bs-option属性を許可
myDefaultAllowList.td = ['data-bs-option']

// 属性を検証するために自分で任意の正規表現を追加できる
// 正規表現がゆるくなりすぎないように注意
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)
※Bootstrap5.1.xの設定例 赤背景が5.2.0での変更箇所
JavaScriptvar myDefaultAllowList = bootstrap.Tooltip.Default.allowList

myDefaultAllowList.table = []

myDefaultAllowList.td = ['data-bs-option']

var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)
※Bootstrap4.xの設定例
JavaScriptvar myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList

myDefaultWhiteList.table = []

myDefaultWhiteList.td = ['data-bs-option']

var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)

DOMPurifyなどの専用ライブラリを使用するためにBootstrapのサニタイザーを回避する場合は、次の手順を実行する必要がある：

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})
※Bootstrap5.1.xの設定例 赤背景が5.2.0での変更箇所
JavaScriptvar yourTooltipEl = document.getElementById('yourTooltip')
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})
※Bootstrap4.xの設定例
JavaScript$('#yourTooltip').tooltip({
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})
【変更履歴】
  • 【v5.0.0-alpha2】
    • whitelist を allowlist に名称変更
  • 【v5.2.0】
    • JavaScriptの記述
      • ES6(ES2015)に変更
      • document.getElementById('ID') ⇒ document.querySelector('#ID')
  • 【v5.3.3】
    • デフォルトの allowList 値のグローバル属性に dd, dl, dt を追加

オプションでjQueryを使用（Optionally using jQuery）v5.0.0-alpha1「引き続きjQueryは使用可能」新設、v5.2.0更新

Bootstrap5ではjQueryは必要ないが、jQueryでコンポーネントを使用することは可能。Bootstrapが window オブジェクトで jQuery を検出すると、jQueryのプラグインシステムにすべてのコンポーネントが追加され、以下のことが可能になる。

設定例
JavaScript// デフォルト設定でツールチップを有効
$('[data-bs-toggle="tooltip"]').tooltip() 

// 指定された構成でツールチップを初期化
$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) 

// `show`メソッドを起動
$('#myTooltip').tooltip('show')

競合の回避（No conflict）v5.2.0設定変更

他のUIフレームワークでBootstrapプラグインを使用する必要がある場合には、名前空間の衝突が起きることがある。この場合は、値を元に戻したいプラグインで .noConflict を呼び出せる。

Bootstrap5.2.0～の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst bootstrapButton = $.fn.button.noConflict() // 以前$.fn.buttonに割り当てられた値に戻す
$.fn.bootstrapBtn = bootstrapButton // $().bootstrapBtnにBootstrapの機能を与える
※Bootstrap5.1.xの設定例 赤背景が5.2.0での変更箇所
JavaScriptvar bootstrapButton = $.fn.button.noConflict()
$.fn.bootstrapBtn = bootstrapButton

Bootstrapは、PrototypeやjQueryのUIのようなサードパーティのJavaScriptライブラリを正式にサポートしていない。.noConflict や名前空間のイベントにもかかわらず、互換性の問題で自分で修正する必要がある場合がある。

【変更履歴】
  • 【v5.2.0】
    • JavaScriptの記述をES6(ES2015)に変更

jQueryイベント（jQuery events）v5.2.0「注意書き」から更新

jQuery が window オブジェクトにあり、<body> に data-bs-no-jquery 属性が設定されていない場合、BootstrapはjQueryを検出する。jQueryが検出された場合、BootstrapはjQueryのイベントシステムのおかげでイベントを発行する。従って、Bootstrapのイベントを監視したい場合は、addEventListener の代わりにjQueryメソッド（.on, .one）を使用する必要がある。

JavaScript$('#myTab a').on('shown.bs.tab', function () {
  // 何かをする...
})

JavaScriptを無効にする（Disabled JavaScript）v5.2.0「JavaScript無効時の特別なフォールバック」から更新

JavaScriptが無効になっていると、Bootstrapのプラグインは特に適切なフォールバックをしない。この場合のユーザーの体験を重視する場合は、<noscript> を使用して状況（とJavaScriptを再度有効にする方法）をユーザーに説明するか、独自のカスタム・フォールバックを追加して下さい。