Skip to main content Skip to docs navigation
Bootstrapの新しいバージョンがあります。

Tooltips (ツールチップ)

CSSとJavaScriptでカスタムBootstrapのツールチップを追加するためのドキュメントと例。

Overview

ツールチッププラグインを使うときに知っておきたいこと

  • Tooltips の配置は 3rd party library Popper に依存します。bootstrap.jsの前にpopper.min.jsをインクルードするか、Tooltips を動作させるためにはPopper.jsをインクルードしたbootstrap.bundle.min.js / bootstrap.bundle.jsを使用する必要があります。
  • Tooltipsはパフォーマンス上の理由でオプトインされているため、自分で初期化する必要があります。
  • 長さゼロのタイトルを持つツールチップは表示されません。
  • 複雑なコンポーネント(入力グループやボタングループなど)でのレンダリングの問題を避けるために container: 'body' を指定します。
  • 隠された要素で tooltips をトリガーすると機能しません。
  • .disableddisabled 要素の tooltips は、ラッパー要素上でトリガされなければなりません。
  • 複数行にまたがるハイパーリンクからトリガーされた場合、tooltips は中央に配置されます。この動作を避けるには、<a>white-space: nowrap; を使用してください。
  • Tooltips は、対応する要素が DOM から削除される前に非表示にしなければなりません。
  • Tooltips は、shadow DOM 内の要素のおかげでトリガーすることができます。
デフォルトでは、このコンポーネントは内蔵のコンテンツサニタイザーを使用しており、明示的に許可されていない HTML 要素を取り除いています。詳細は、JavaScript ドキュメントの sanitizer セクションを参照してください。
このコンポーネントのアニメーション効果は、prefers-reduced-motionメディアクエリに依存します。アクセシビリティドキュメントの reduced motion セクションを参照してください。

サンプルを参考にしてください。

Example: Enable tooltips everywhere

ページ上のすべてのツールチップを初期化する1つの方法は、 data-bs-toggle属性でツールチップを選択することです。

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

Examples

下のリンクにカーソルを合わせると、ツールチップが表示されます。

Placeholder text to demonstrate some inline links with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of real text. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how these tooltips on links can work in practice, once you use them on your own site or project.

下のボタンにカーソルを合わせると、上、右、下、左の4つのツールチップの方向が表示されます。

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip on left">
  Tooltip on left
</button>

Cutom HTML を追加した場合

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

With an SVG:

Sass

Variables

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer / 4;
$tooltip-padding-x:                 $spacer / 2;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

Usage

tooltip プラグインは、オンデマンドでコンテンツとマークアップを生成し、デフォルトではトリガー要素の後にツールチップを配置します。

JavaScript で tooltip をトリガーする場合:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Overflow auto and scroll

Tooltip の位置は、親コンテナに .table-responsive のように overflow:autooverflow:scroll がある場合に自動的に変更されますが、元の配置の位置は保持されます。 解決するには、 boundary オプションをデフォルト値 'scrollParent' 以外(例えば 'window')に設定します。

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: document.body // or document.querySelector('#boundary')
})

Markup

Tooltip に必要なマークアップは、 Tooltip を作成したいHTML要素の data 属性と title だけです。 Tooltip のマークアップは単純ですが、位置を指定する必要があります(デフォルトではプラグインによって top に設定されています)。

Making tooltips work for keyboard and assistive technology users

Tooltips を追加すべきなのは、キーボードフォーカスが可能でインタラクティブなHTML要素(リンクやフォームコントロールなど)のみです。 任意のHTML要素( <span> など)は、tabindex="0" 属性を追加することでフォーカス可能にすることができますが、 これはキーボードユーザにとっては非インタラクティブな要素のタブストップが追加されてしまうので、 キーボードユーザが混乱する可能性があり、現在ほとんどの支援技術はこのような状況でのツールチップをアナウンスしません。 また、ツールチップのトリガーとして hover だけに頼ってはいけません。これにより、キーボードユーザーが Tooltips をトリガーできなくなります。

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

Disabled elements

disabled属性を持つ要素はインタラクティブではありません。つまり、ユーザーはそれらにフォーカスしたり、ホバーしたり、クリックしたりしてツールチップ(またはポップオーバー)をトリガーすることはできません。 回避策としては、ラッパー <div><span> でツールチップをトリガーし、理想的には tabindex="0" でキーボードフォーカス可能にして、 無効要素の pointer-events をオーバーライドします。

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Options

オプションは、データ属性またはJavaScriptで渡すことができます。データ属性の場合は、 data-bs-animation =" "のように、オプション名を data-bs-に追加します。 データ属性でオプションを渡す場合は, 必ずオプション名のケースタイプを camelCase から kebab-case に変更してください。 たとえば、 data-bs-customClass =" beautifier "を使用する代わりに、 data-bs-custom-class =" beautifier "を使用します。

セキュリティ上の理由から、sanitize, sanitizeFn および allowList オプションはデータ属性を用いて指定することができないことに注意してください。
Name Type Default Description
animation boolean true CSSのフェード遷移を適用します。
container string | element | false false

特定の要素に tooltip を追加します。例 container: 'body'. このオプションは、文書の流れの中で tooltip をトリガ要素の近くに配置することができるので、便利です。 - ウィンドウのサイズ変更中にツールチップがトリガー要素から離れて浮いてしまうのを防ぐためのものです。

delay number | object 0

tooltip の表示と非表示の時間 (ms) - 手動トリガータイプには適用されません。

数値が与えられた場合、非表示/表示の両方に遅延が適用されます。

オブジェクト構造は delay: { "show": 500, "hide": 100 }

html boolean false

HTMLを許可する。

trueの場合、 title 内のHTMLタグが tooltip 内にレンダリングされます。 innerText プロパティは DOM にコンテンツを挿入するために使用されます。

XSS攻撃が気になる場合はテキストを使用してください。

placement string | function 'top'

配置方法 - auto | top | bottom | left | right.
When auto を指定すると、動的に tooltip の向きを変えてくれます。

配置を決定するために関数を使用する場合、tooltip DOMノードを第1引数に、トリガー要素DOMノードを第2引数にして呼び出されます。this コンテキストには、tooltip のインスタンスが設定されます。

selector string | false false セレクターが提供されている場合、tooltip オブジェクトは指定されたターゲットに委任されます。 実際には、これは動的に追加されたDOM要素に tooltip を適用するためにも使用されます (jQuery.on support). 総裁は thisan informative exampleを参考にしてくさい。
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'

tooltip を作成する際に使用する基本HTML。

ツールチップのtitle.tooltip-innerに適用されます。

.tooltip-arrow が tooltip の矢印になります。

一番外側のラッパー要素は、.tooltipクラスとrole="tooltip"を持っていなければなりません。

title string | element | function ''

title属性が存在しない場合のデフォルトのタイトル値。

関数が与えられた場合は、そのthis 参照がツールチップが添付されている要素に設定された状態で呼び出されます。

trigger string 'hover focus'

トリガーの方法 - click | hover | focus | manual. 複数のトリガーを渡すことができます。

'manual' は、tooltip が .tooltip('show') を介してプログラムでトリガーされることを示します。.tooltip('hide') および .tooltip('toggle') メソッド; この値は他のトリガーと組み合わせることはできません。

'hover'を単独で使用すると、キーボードからトリガーすることができない tooltip になります。

fallbackPlacements array ['top', 'right', 'bottom', 'left'] フォールバック時に Popper がどの位置を使用するかを指定することができます。 詳細は Popper.js's behavior docsを参考にしてください。
boundary string | element 'clippingParents' オーバーフロー制約境界。 デフォルトでは 'clippingParents' であり, HTMLElement reference (JavaScript のみ) の値を受け取ります。詳細は Popper's detectOverflow docsを参考にしてください。
customClass string | function ''

Add classes to the tooltip when it is shown. Note that these classes will be added in addition to any classes specified in the template. To add multiple classes, separate them with spaces: 'class-1 class-2'.

You can also pass a function that should return a single string containing additional class names.

sanitize boolean true Enable or disable the sanitization. If activated 'template' and 'title' options will be sanitized. See the sanitizer section in our JavaScript documentation.
allowList object Default value 許可された属性とタグを含むオブジェクト
sanitizeFn null | function null ここでは、独自のサニタイズ関数を指定することができます。これは、サニタイズを実行するために専用のライブラリを使いたい場合に便利です。
offset array | string | function [0, 0]

Offset of the tooltip relative to its target. You can pass a string in data attributes with comma separated values like: data-bs-offset="10,20"

When a function is used to determine the offset, it is called with an object containing the popper placement, the reference, and popper rects as its first argument. The triggering element DOM node is passed as the second argument. The function must return an array with two numbers: [skidding, distance].

For more information refer to Popper's offset docs.

popperConfig null | object | function null

To change Bootstrap's default Popper config, see Popper's configuration.

When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper.

Data attributes for individual tooltips

個々の tooltip のオプションは、上で説明したように、データ属性を使用して指定することもできます。

Using function with popperConfig

var tooltip = new bootstrap.Tooltip(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Methods

非同期のメソッドとトランジション

すべての API メソッドは非同期で、トランジションを開始します。トランジションが開始されると同時に呼び出し元に返されますが、トランジションが終了する前に返されます。また、遷移中のコンポーネントに対するメソッドコールは無視されます

詳しくは JavaScript のドキュメントをご覧ください

show

tooltip 要素を表示します。 tooltip が実際に表示される前に呼び出し元に戻ります。 (shown.bs.tooltip が発生する前). “manual” トリガーとみなされます。tooltip のトリガを設定します。長さゼロのタイトルの場合は tooltip は表示されません。

tooltip.show()

hide

tooltip 要素を非表示します。 tooltip が実際に隠される前に呼び出し元に戻ります。 (hidden.bs.tooltip が発生した時). “manual” トリガーとみなされます

tooltip.hide()

toggle

tooltip 要素をトグルします。 tooltip が実際に表示または非表示になる前に呼び出し元に戻ります。 ( shown.bs.tooltip または hidden.bs.tooltip が発生した時).“manual” トリガーとみなされます。

tooltip.toggle()

dispose

tooltip 要素を非表示して、破棄します。 委任を使用するツールチップは (the selector option を使用している) 子孫のトリガ要素を個別に破壊することはできません。

tooltip.dispose()

enable

tooltip 要素に表示する機能を与えます。. デフォルトで有効になっています。

tooltip.enable()

disable

tooltip 要素を表示する機能を削除します。tooltip は再有効化された場合にのみ表示されます。

tooltip.disable()

toggleEnabled

tooltip 要素の表示・非表示を切り替えます。

tooltip.toggleEnabled()

update

tooltip 要素の位置を更新します。

tooltip.update()

getInstance

DOM要素に関連付けられたツールチップインスタンスを取得できる静的メソッド

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

Events

Event type Description
show.bs.tooltip showインスタンスメソッドが呼び出されたときにすぐに発生します。
shown.bs.tooltip tooltip がユーザーに表示されたときに発生します(CSS トランジションが完了するのを待ちます)。
hide.bs.tooltip hideインスタンスメソッドが呼び出されたときに発生します。
hidden.bs.tooltip tooltip の非表示が完了したときに発生します(CSS トランジションが完了するのを待ちます)。
inserted.bs.tooltip tooltip が DOM に追加されて、show.bs.tooltip イベントの後に発生します。
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
  // do something...
})

tooltip.hide()