ツールチップ
ツールチップは、ユーザーが要素を操作したときに表示される、簡潔で有益なメッセージを表示します。
インストール
npx nextui-cli@latest add tooltip
上記のコマンドは個別のインストール専用です。もし@nextui-org/reactが既にグローバルにインストールされている場合は、このステップをスキップできます。@nextui-org/reactが既にグローバルにインストールされている場合は、このステップをスキップできます。
インポート
個別のインストールの場合、ツールチップはポップオーバースタイルを再利用するため、
./node_modules/@nextui-org/theme/dist/components/popover.jsをtailwind.config.jsファイルに追加する必要があることに注意してください。
使用方法
矢印付き
色
配置
オフセット
制御
遅延付き
open および close の遅延を delay および closeDelay プロパティで制御できます。
2 番目のボタンにカーソルを合わせると、ツールチップがすぐに表示されます。別の要素にカーソルを合わせる前に遅延を待つと、遅延が再開されます。
カスタムコンテンツ
カスタムモーション
ツールチップは、enter / exit アニメーションをカスタマイズするための motionProps プロパティを提供します。
Framer motion のバリアントについて詳しくはこちらをご覧ください。
スロット
- base：メインのツールチップスロットで、ツールチップコンテンツをラップします。
- arrow：矢印スロットで、ツールチップの矢印をラップします。矢印の配置はツールチップの配置に基づきます。例えば、
data-[placement=top]:...のように設定します。
カスタムスタイル
カスタムの Tailwind CSS クラスをコンポーネントのスロットに渡すことで、Tooltip コンポーネントをカスタマイズできます。
データ属性
Tooltip の base 要素には、以下の属性があります。
- data-open：ツールチップが開いている場合。ツールチップの状態に基づきます。
- data-placement：ツールチップの配置。
placementプロパティに基づきます。矢印要素はこの属性に基づいて配置されます。 - data-disabled：ツールチップが無効になっている場合。
isDisabledプロパティに基づきます。
アクセシビリティ
- キーボードフォーカスの管理と、クロスブラウザの正規化。
- ホバーの管理と、クロスブラウザの正規化。
- スクリーンリーダーのラベル付けサポート（aria-describedby）。
- ARIA を介して支援技術にツールチップとして公開。
- 最初のツールチップのホバー時の遅延、および後続のツールチップの遅延なしのネイティブツールチップの動作と一致。
API
ツールチップのプロパティ
| 属性 | タイプ | 説明 | デフォルト |
|---|---|---|---|
| children* | ReactNode[] | レンダリングする子要素。通常はトリガー要素です。 | - |
| content | ReactNode | ツールチップ内にレンダリングするコンテンツ。 | - |
| size | sm | md | lg | ツールチップのサイズ。これは content のフォントサイズを変更します。 | md |
| color | default | primary | secondary | success | warning | danger | ツールチップのカラーテーマ。 | default |
| radius | none | sm | md | lg | full | ツールチップのボーダー半径。 | md |
| shadow | none | sm | md | lg | ツールチップの影。 | sm |
| placement | TooltipPlacement | トリガーリファレンスに対するツールチップの配置。 | top |
| delay | number | ツールチップが開くまでの遅延時間（ミリ秒単位）。 | 0 |
| closeDelay | number | ツールチップが閉じるまでの遅延時間（ミリ秒単位）。 | 500 |
| isOpen | boolean | ツールチップがデフォルトで開いているかどうか（制御付き）。 | - |
| defaultOpen | boolean | ツールチップがデフォルトで開いているかどうか（制御なし）。 | - |
| offset(px) | number | リファレンスとポッパー間の距離またはマージン。オフセットモディファイアを作成するために内部的に使用されます。 | 7 |
| containerPadding(px) | number | 要素とその周囲のコンテナの間に適用する必要がある配置パディング。 | 12 |
| crossOffset(px) | number | 要素とアンカー要素の間で、クロス軸に沿って適用される追加のオフセット。 | 0 |
| showArrow | boolean | ツールチップに矢印を表示するかどうか。 | false |
| shouldFlip | boolean | ツールチップが境界領域からオーバーフローしそうな場合に、配置を変更して反転するかどうか。 | true |
| triggerScaleOnOpen | boolean | ツールチップが開いているときにトリガーをスケールダウンするかどうか。 | true |
| shouldBlockScroll | boolean | ツールチップの外側のスクロールをブロックするかどうか。 | true |
| isKeyboardDismissDisabled | boolean | ツールチップを閉じるために Escape キーを押すのを無効にするかどうか。 | false |
| isDismissable | boolean | ユーザーがツールチップの外側を操作したときにオーバーレイを閉じるかどうか。 | false |
| shouldCloseOnBlur | boolean | フォーカスが失われたり、外に移動したりした場合に、ツールチップを閉じるかどうか。 | true |
| motionProps | MotionProps | Framer motion のアニメーションを変更するためのプロパティ。variants API を使用して、独自のアニメーションを作成します。 | - |
| portalContainer | HTMLElement | オーバーレイポータルが配置されるコンテナ要素。 | document.body |
| updatePositionDeps | any[] | ツールチップの位置更新を強制するための依存関係。 | [] |
| isDisabled | boolean | ツールチップを無効にするかどうか。 | false |
| disableAnimation | boolean | ツールチップをアニメーション化するかどうか。 | false |
| classNames | Record<"base"｜"content", string> | ツールチップのスロットにカスタムクラス名を適用できるようにします。 | - |
ツールチップイベント
| 属性 | タイプ | 説明 |
|---|---|---|
| onOpenChange | (isOpen: boolean) => void | ツールチップの開閉状態が変更されたときに呼び出されるハンドラー。 |
| shouldCloseOnInteractOutside | (e: HTMLElement) => void | ユーザーがツールチップのrefの外の引数要素とインタラクションしたときに、onCloseを呼び出す必要がある場合はtrueを返します。これにより、ツールチップを閉じるべきではない要素とのインタラクションを除外する機会が得られます。デフォルトでは、オーバーレイrefの外でのインタラクションに対して常にonCloseが呼び出されます。 |
| onClose | () => void | ツールチップを閉じる必要があるときに呼び出されるハンドラー。 |
ツールチップのタイプ
ツールチップの配置
type TooltipPlacement =| "top"| "bottom"| "right"| "left"| "top-start"| "top-end"| "bottom-start"| "bottom-end"| "left-start"| "left-end"| "right-start"| "right-end";
モーションプロパティ
export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/
