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

スクロールスパイ(ScrollSpy) v5.2.0設定変更

スクロール位置に基づいてBootstrapナビゲーションまたはリストグループコンポーネントを自動的に更新して、ビューポートで現在アクティブなリンクを示す。

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

使い方(How it works)

スクロールスパイは、アンカーの href によって参照される id を持つ要素がスクロールされて表示されるときに、アンカー(<a>)要素の .active クラスを切り替える。スクロールスパイは、Bootstrapのナビゲーションコンポーネントリストグループと組み合わせるのが最適だが、現在のページの任意のアンカー要素でも機能する。その仕組みは次のとおり。

  • まず、スクロールスパイには、ナビゲーション、リストグループ、単純なリンクセットと、スクロール可能なコンテナの2つが必要。スクロール可能なコンテナは、<body>heightoverflow-y:scroll が設定されたカスタム要素にする。
  • スクロール可能なコンテナに、data-bs-spy="scroll"data-bs-target="#navId" を追加する。navId は、関連付けられたナビゲーションの唯一の id。キーボードアクセスを確実にするために、tabindex="0" も入れる。
  • "スパイ"コンテナをスクロールすると、.active クラスが追加され、関連するナビゲーション内のアンカーリンクから削除される。リンクには解決可能な id ターゲットが必要。そうでない場合、リンクは無視される。例えば、<a href="#home">home</a> は、<div id="home"></div> などのDOM内の何かに対応している必要がある。
  • 表示されていないターゲット要素は無視される。後述の非表示要素の項目を参照して下さい。
【変更履歴】
  • 【v5.2.0】
    • 交差オブザーバー API(Intersection Observer API)を使用するように書き直され、相対的な親ラッパーが不要に(設定がナビゲーションとリストグループに限定されなくなった)

実例(Examples)

ナビゲーションバーの下の領域をスクロールし、アクティブなクラスの変更を確認。ドロップダウンアイテムも強調表示される。

見本

第1の見出し

ゆっくり下へスクロールしてみて下さい。

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

第2の見出し

スクロールの一番上が第2の見出しになると上部のナビゲーションバーの第2の見出しの部分がアクティブに変わります。

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

第3の見出し

スクロールの一番上が第3の見出しになると上部のナビゲーションバーのアクティブの部分がドロップダウンに変わり、ドロップメニューの第3の見出しの部分がアクティブになります。

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

第4の見出し

スクロールの一番上が第4の見出しになると上部のナビゲーションバーのアクティブの部分がドロップダウンに変わり、ドロップメニューの第4の見出しの部分がアクティブになります。

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

第5の見出し

スクロールの一番上が第5の見出しになると上部のナビゲーションバーのアクティブの部分がドロップダウンに変わり、ドロップメニューの第5の見出しの部分がアクティブになります。

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

Bootstrap5.xの設定例 緑背景が変更箇所
<nav id="navbar-example2" class="navbar bg-light px-3 mb-3">
  <a class="navbar-brand" href="#">ブランド</a>
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading1">第1</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">第2</a>
    </li>
    <li class="nav-item dropdown">
      <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">ドロップダウン</a>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#scrollspyHeading3">第3</a></li>
        <li><a class="dropdown-item" href="#scrollspyHeading4">第4</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#scrollspyHeading5">第5</a></li>
      </ul>
    </li>
  </ul>
</nav>
<div class="p-3 mt-2 overflow-auto" data-bs-spy="scroll" data-bs-target="#navbar-example2" data-bs-root-margin="0px 0px -40%" data-bs-smooth-scroll="true" tabindex="0" style="height:200px">
  <h4 id="scrollspyHeading1">第1の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">第2の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">第3の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">第4の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">第5の見出し</h4>
  <p>...</p>
</div>
※Bootstrap4.xの設定例 赤背景が変更箇所
<nav id="navbar-example2" class="navbar navbar-light bg-light">
  <a class="navbar-brand" href="#">ブランド</a>
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading1">第1</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">第2</a>
    </li>
    <li class="nav-item dropdown">
      <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-expanded="false">ドロップダウン</a>
      <div class="dropdown-menu">
        <a class="dropdown-item" href="#scrollspyHeading3">第3</a>
        <a class="dropdown-item" href="#scrollspyHeading4">第4</a>
        <div role="separator" class="dropdown-divider"></div>
        <a class="dropdown-item" href="#scrollspyHeading5">第5</a>
      </div>
    </li>
  </ul>
</nav>
<div class="p-3 mt-2" data-spy="scroll" data-target="#navbar-example2" data-offset="0">
  <h4 id="scrollspyHeading1">第1の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">第2の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">第3の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">第4の見出し</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">第5の見出し</h4>
  <p>...</p>
</div>
【設定】
  • 《ナビゲーションバーの設定》+ [data-bs-spy="scroll"][data-bs-target="ナビゲーションバーのID"]
【注意】
  • <body> 以外の要素に [data-bs-spy="scroll"] を設定する場合は [tabindex="0"] を入れる
  • ナビゲーションバーで使用する際には、ul.nav.navbar-navナビゲーションバーのナビゲーション)ではなく、ul.nav.nav-pillsピルナビゲーション)に設定すること
    折り畳み式にする場合は、nav.navbar.navbar-expand-* > div.container-fluid > div.collapse.navbar-collapse > ul.nav.nav-pills.flex-column.flex-*-row の形式にする(* に入れるブレイクポイントは統一する)
  • スクロールをスムーズにしたい場合は、[data-bs-spy="scroll"][data-bs-smooth-scroll="true"] を入れる
【変更履歴】

入れ子のナビゲーション(Nested nav)

スクロールスパイプラグインは入れ子になった .nav でも動作できる。入れ子になった .nav.active の場合、その親も .active になる。ナビゲーションの横にある領域をスクロールして、アクティブなクラスの変更を確認。

見本

アイテム 1

アイテム 1の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

JavaScriptプラグインは、表示される可能性のあるすべての要素の中から適切な要素を選択しようとすることに注意。同時に複数の目に見えるスクロールスパイターゲットは、いくつかの問題を引き起こす可能性がある。

アイテム 1-1

アイテム 1-1の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

JavaScriptプラグインは、表示される可能性のあるすべての要素の中から適切な要素を選択しようとすることに注意。同時に複数の目に見えるスクロールスパイターゲットは、いくつかの問題を引き起こす可能性がある。

アイテム 1-2

アイテム 1-2の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

JavaScriptプラグインは、表示される可能性のあるすべての要素の中から適切な要素を選択しようとすることに注意。同時に複数の目に見えるスクロールスパイターゲットは、いくつかの問題を引き起こす可能性がある。

アイテム 2

アイテム 2の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

JavaScriptプラグインは、表示される可能性のあるすべての要素の中から適切な要素を選択しようとすることに注意。同時に複数の目に見えるスクロールスパイターゲットは、いくつかの問題を引き起こす可能性がある。

アイテム 3

アイテム 3の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

JavaScriptプラグインは、表示される可能性のあるすべての要素の中から適切な要素を選択しようとすることに注意。同時に複数の目に見えるスクロールスパイターゲットは、いくつかの問題を引き起こす可能性がある。

アイテム 3-1

アイテム 3-1の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

JavaScriptプラグインは、表示される可能性のあるすべての要素の中から適切な要素を選択しようとすることに注意。同時に複数の目に見えるスクロールスパイターゲットは、いくつかの問題を引き起こす可能性がある。

アイテム 3-2

アイテム 3-2の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

JavaScriptプラグインは、表示される可能性のあるすべての要素の中から適切な要素を選択しようとすることに注意。同時に複数の目に見えるスクロールスパイターゲットは、いくつかの問題を引き起こす可能性がある。

Bootstrap5.xの設定例 緑背景が変更箇所
HTML<div class="row">
  <div class="col-4">
    <nav id="navbar-example3" class="h-100 flex-column align-items-stretch pe-4 border-end">
      <nav class="nav nav-pills flex-column">
        <a class="nav-link active" href="#item-1">アイテム 1</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-1-1">アイテム 1-1</a>
          <a class="nav-link ms-3 my-1" href="#item-1-2">アイテム 1-2</a>
        </nav>
        <a class="nav-link" href="#item-2">アイテム2</a>
        <a class="nav-link" href="#item-3">アイテム3</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-3-1">アイテム 3-1</a>
          <a class="nav-link ms-3 my-1" href="#item-3-2">アイテム 3-2</a>
        </nav>
      </nav>
    </nav>
  </div>
  <div class="col-8">
    <div class="overflow-auto" data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-smooth-scroll="true" tabindex="0" style="height:350px">
      <div id="item-1">
        <h4>アイテム 1</h4>
        <p>アイテム 1の文章です。...</p>
      </div>
      <div id="item-1-1">
        <h5>アイテム 1-1</h5>
        <p>アイテム 1-1の文章です。...</p>
      </div>
      <div id="item-1-2">
        <h5>アイテム 1-2</h5>
        <p>アイテム 1-2の文章です。...</p>
      </div>
      <div id="item-2">
        <h4>アイテム 2</h4>
        <p>アイテム 2の文章です。...</p>
      </div>
      <div id="item-3">
        <h4>アイテム 3</h4>
        <p>アイテム 3の文章です。...</p>
      </div>
      <div id="item-3-1">
        <h5>アイテム 3-1</h5>
        <p>アイテム 3-1の文章です。...</p>
      </div>
      <div id="item-3-2">
        <h5>アイテム 3-2</h5>
        <p>アイテム 3-2の文章です。...</p>
      </div>
    </div>
  </div>
</div>
【設定】
  • 《入れ子の縦積みピルナビゲーション》+ div[data-bs-spy="scroll"][data-bs-target="ナビゲーションの親要素のID"][tabindex="0"]
【変更履歴】
  • 【v5.0.0-alpha1】
    • 縦積みピルナビゲーションバー:.navbar.flex-column.align-items-stretch.p-3 を追加
  • 【v5.0.0-alpha2】
    • [data-spy="scroll"](現 [data-bs-spy="scroll"])に、[tabindex="0"] を入れる
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-spy="scroll"][data-bs-spy="scroll"]
      • [data-target="ナビゲーションの親要素のID"][data-bs-target="ナビゲーションの親要素のID"]
      • [data-offset][data-bs-offset]
    • RTL(右書き)の設定追加に伴い空白ユーティリティのクラス名変更
      • .ml-3.ms-3
  • 【v5.2.0】
    • 縦積みピルナビゲーションの親要素:ナビゲーションバー形式を廃止 .navbar.flex-column.align-items-stretch.p-3.h-100.flex-column.align-items-stretch.pe-4.border-enda.navbar-brand も削除)
    • [data-bs-offset] は非推奨になったので削除
    • [data-bs-smooth-scroll](スムーズなスクロールが有効)を追加

リストグループ(List group)

スクロールスパイプラグインは .list-group でも動作。リストグループの横にある領域をスクロールして、アクティブなクラスの変更を確認する。

見本

アイテム 1

アイテム 1の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

アイテム 2

アイテム 2の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

アイテム 3

アイテム 3の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

アイテム 4

アイテム 4の文章です。
これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

設定例
<div class="row">
  <div class="col-4">
      <div id="list-example" class="list-group">
      <a class="list-group-item active list-group-item-action" href="#list-item-1">アイテム 1</a>
      <a class="list-group-item list-group-item-action" href="#list-item-2">アイテム 2</a>
      <a class="list-group-item list-group-item-action" href="#list-item-3">アイテム 3</a>
      <a class="list-group-item list-group-item-action" href="#list-item-4">アイテム 4</a>
    </div>
  </div>
  <div class="col-8">
    <div class="overflow-auto" data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" tabindex="0" style="height:200px">
      <h4 id="list-item-1">アイテム 1</h4>
      <p>アイテム 1の文章です。...</p>
      <h4 id="list-item-2">アイテム 2</h4>
      <p>アイテム 2の文章です。...</p>
      <h4 id="list-item-3">アイテム 3</h4>
      <p>アイテム 3の文章です。...</p>
      <h4 id="list-item-4">アイテム 4</h4>
      <p>アイテム 4の文章です。...</p>
    </div>
  </div>
</div>
【設定】
【変更履歴】
  • 【v5.0.0-alpha2】
    • [data-spy="scroll"](現 [data-bs-spy="scroll"])に、[tabindex="0"] を入れる
  • 【v5.0.0-beta1】
    • data- 属性に名前空間 bs- を追加
      • [data-spy="scroll"][data-bs-spy="scroll"]
      • [data-target="リストグループのID"][data-bs-target="リストグループのID"]
      • [data-offset][data-bs-offset]
  • 【v5.2.0】
    • [data-bs-offset] は非推奨になったので削除
    • [data-bs-smooth-scroll](スムーズなスクロールが有効)を追加

単純なアンカー(Simple anchors)v5.2.0新設

スクロールスパイは、ナビゲーションコンポーネントとリストグループに限定されないため、現在のドキュメント内のすべての <a> アンカー要素で機能する。エリアをスクロールして、.active クラスの変更を確認する。

見本

アイテム 1

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

アイテム 2

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

アイテム 3

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

アイテム 4

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

アイテム 5

これは、スクロールスパイページのプレースホルダコンテンツ。ページを下にスクロールすると、適切なナビゲーションリンクが強調表示される。これは、コンポーネントの実例全体で繰り返される。スクロールとハイライトを強調するために、ここにいくつかのサンプルコピーを繰り返し追加している。

設定例
HTML<div class="row">
  <div class="col-4">
    <div id="list-example" class="d-flex flex-column gap-2 text-center simple-list-example-scrollspy">
      <a href="#item-1" class="p-1 rounded">アイテム 1</a>
      <a href="#item-2" class="p-1 rounded">アイテム 2</a>
      <a href="#item-3" class="p-1 rounded">アイテム 3</a>
      <a href="#item-4" class="p-1 rounded">アイテム 4</a>
    </div>
  </div>
  <div class="col-8">
    <div class="overflow-auto" data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" tabindex="0" style="height:200px">
      <h4 id="item-1">アイテム 1</h4>
      <p>...</p>
      <h4 id="item-2">アイテム 2</h4>
      <p>...</p>
      <h4 id="item-3">アイテム 3</h4>
      <p>...</p>
      <h4 id="item-4">アイテム 4</h4>
      <p>...</p>
    </div>
  </div>
</div>
SCSS.simple-list-example-scrollspy {
  .active {
    background-color: rgba(var(--bs-secondary-rgb), .15);
  }
}
CSS.simple-list-example-scrollspy .active {
  background-color: rgba(var(--bs-secondary-rgb), .15);
}
【設定】
  • 一般的なアンカーリンク + div[data-bs-spy="scroll"][data-bs-target="リンクの親要素のID"][tabindex="0"]
【注意】
  • .active 用に任意にSCSSかCSSの設定が必要

非表示要素(Non-visible elements)v5.2.0新設

表示されていないターゲット要素は無視され、対応するナビゲーションアイテムは .active クラスを受け取らない。非表示のラッパー要素で初期化されたスクロールスパイ・インスタンスは、すべてのターゲット要素を無視。ラッパーが表示されたら、refresh メソッドを使用して監視可能な要素を確認する。

設定例
JavaScriptdocument.querySelectorAll('#nav-tab>[data-bs-toggle="tab"]').forEach(el => {
  el.addEventListener('shown.bs.tab', () => {
    const target = el.getAttribute('data-bs-target')
    const scrollElem = document.querySelector(`${target} [data-bs-spy="scroll"]`)
    bootstrap.ScrollSpy.getOrCreateInstance(scrollElem).refresh()
  })
})

使用方法(Usage)

データ属性経由で(Via data attributes)

スクロールバーの動作をトップバーのナビゲーションに簡単に追加するには、追従する要素(通常は<body>)に data-bs-spy="scroll" を追加。次に、任意のBootstrap .nav コンポーネントの親要素のIDかクラス名を data-bs-target 属性に追加。

設定例
HTML<body data-bs-spy="scroll" data-bs-target="#navbar-example">
  ...
  <div id="navbar-example">
    <ul class="nav nav-tabs" role="tablist">
      ...
    </ul>
  </div>
  ...
</body>

JavaScript経由で(Via JavaScript)v5.2.0設定変更

Bootstrap5.2.0~の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst scrollSpy = new bootstrap.ScrollSpy(document.body, {
  target: '#navbar-example'
})
※Bootstrap5.1.3の設定例 赤背景が5.2.0での変更箇所
JavaScriptvar scrollSpy = new bootstrap.ScrollSpy(document.body, {
  target: '#navbar-example'
})
※Bootstrap4.xの設定例
JavaScript$('body').scrollspy({ target: '#navbar-example' })
【変更履歴】
  • 【v5.0.0-alpha1】
    • JavaScriptの記述をjQueryに依存しない方法に変更
  • 【v5.2.0】
    • JavaScriptの記述をES6(ES2015)に変更

オプション(Options)v5.2.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値を格納できる。

名前 タイプ デフォルト 説明
rootMargin
v5.2.0追加、v5.2.1修正
string 0px 0px -25% スクロール位置を計算するときの交差オブザーバーrootMarginの有効な単位。
smoothScroll
v5.2.0追加
boolean false ユーザーがスクロールスパイオブザーバブルを参照するリンクをクリックしたときにスムーズなスクロールを有効にする。
target
v5.2.1修正
string | DOM element null スクロールスパイプラグインを適用する要素を指定。
threshold
v5.2.1追加
array [0.1, 0.5, 1] スクロール位置を計算するときの IntersectionObserver thresholdの有効な入力。
【変更履歴】
  • 【v5.2.0】
    • offsetmethod を非推奨にし、rootMarginsmoothScroll を追加
  • 【v5.2.1】
    • threshold を追加
    • rootMargin のデフォルトを 0px 0px -40% から 0px 0px -25%に修正
    • target のタイプから jQuery object を外し、デフォルトを null に修正

メソッド(Methods)v5.0.2追加、v5.2.0設定変更

メソッド 説明
dispose 要素のスクロールスパイを破棄(DOM要素に保存されているデータを削除)。
getInstance
v5.0.0-alpha1追加
DOM要素に関連付けられたスクロールスパイ・インスタンスを取得するための静的メソッド。
getOrCreateInstance
v5.0.2追加
DOM要素に関連付けられたスクロールスパイ・インスタンスを取得したり、初期化されていない場合に新しいインスタンスを作成するための静的メソッド。
refresh DOMで要素を追加や削除するときは、refreshメソッドを呼び出す必要がある。

refreshメソッドを使用した例を以下に表示:

Bootstrap5.2.0~の設定例 緑背景が5.2.0での変更箇所
JavaScriptconst dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
  bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})
※Bootstrap5.1.3の設定例 赤背景が5.2.0での変更箇所
JavaScriptvar dataSpyList = [].slice.call(document.querySelectorAll('[data-bs-spy="scroll"]'))
dataSpyList.forEach(function (dataSpyEl) {
  bootstrap.ScrollSpy.getInstance(dataSpyEl)
    .refresh()
})
※Bootstrap4.xの設定例
JavaScript$('[data-spy="scroll"]').each(function () {
  var $spy = $(this).scrollspy('refresh')
})
【変更履歴】
  • 【v5.0.0-alpha1】
    • $().scrollspy('xxx')scrollspy.xxx()
    • getInstance メソッドが追加
  • 【v5.0.2】
    • getOrCreateInstance メソッドが追加
  • 【v5.2.0】
    • JavaScriptの記述をES6(ES2015)に変更

イベント(Events)

イベントタイプ 説明
activate.bs.scrollspy このイベントは、スクロールスパイによってアンカーがアクティブ化されるたびにスクロール要素で発動。
使用例 v5.2.0設定変更
JavaScriptconst firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // 何かをする...
})