Tooltips
English ·
Español ·
Français ·
Português ·
中文 ·
日本語
—
Demo
純粋な CSS のツールチップライブラリ。JavaScript なし、依存関係なし、設定不要。未対応ブラウザへのフォールバック付き、圧縮後約 0.5 KB（Brotli）
## JavaScript ベースのライブラリではなくこれを選ぶ理由
ほとんどのツールチップライブラリは、位置の計算、イベントリスナーの登録、表示状態の管理に JavaScript を必要とします。このライブラリはそのいずれも行いません——すべての動作は CSS で宣言されています。
## 特徴
* **純粋な CSS。** JavaScript、依存関係、設定は不要です。
* **ネイティブポジショニング。** CSS Anchor Positioning を使用して位置を計算し、スペースが不足した場合に自動的に反対側へ切り替えます。
* **最小限のコード。** スタイルシートには基本動作に必要なルールのみが含まれており、使用しないかもしれない位置・スタイル・アニメーションのクラスは含まれていません。
* **CSS による設定。** 各ツールチップは、CSS カスタムプロパティを通じてプロジェクトのニーズに応じた位置・外観・アニメーションを定義できます。
* **レイアウトシフトなし。** ポジショニングはブラウザのレイアウト計算中に行われ、レンダリング後に DOM を測定することはありません。
* **アクセシブル。** `aria-label` をコンテンツとして使用し、`:focus` 時にツールチップを表示します。
* **自動フォールバック。** CSS Anchor Positioning に対応していないブラウザは、上部中央の絶対配置を使用します。
> [!IMPORTANT]
> CSS Anchor Positioning は比較的新しいブラウザ機能です。対応していないブラウザは、動的配置ではなく予測可能なフォールバック（中央上部のバブル、絶対配置）を受け取ります。
## インストール
### npm
```bash
npm i @zkreations/tooltips
```
### フレームワークとバンドラー
パッケージはデフォルトのスタイルエントリとして圧縮された CSS をエクスポートします：
```js
import '@zkreations/tooltips';
```
アプリケーションのエントリポイントで一度だけインポートします：
**Next.js**
```tsx
// app/layout.tsx or pages/_app.tsx
import '@zkreations/tooltips';
```
**Astro**
```astro
---
import '@zkreations/tooltips';
---
```
同じインポートは Vite、Nuxt、SvelteKit、および CSS パッケージインポートをサポートする他のバンドラーでも動作します。バンドラーがパッケージのスタイルエントリを解決できない場合は、ファイルを直接インポートします：
```js
import '@zkreations/tooltips/index.min.css';
```
両方のパスをインポートしないでください——同じスタイルシートが含まれています。
### Sass
プロジェクトでソースをコンパイルする必要がある場合にのみ Sass エントリを使用します：
```scss
@use '@zkreations/tooltips/scss/tooltip';
```
その場合、パッケージの CSS もインポートしないでください。ほとんどのプロジェクトはコンパイル済みの CSS エントリを使用すべきです。
### CDN
```html
```
## 使い方
任意の HTML 要素に `.tooltip` クラスと `aria-label` 属性を追加します：
```html
```
### ポジショニング
ツールチップはデフォルトで上部（`block-start`）に表示され、スペースが不足した場合は自動的に反転（`flip-block, flip-inline`）します：
```css
.tooltip::before {
position-area: var(--tt-area, block-start);
position-try-fallbacks: var(--tt-fallbacks, flip-block, flip-inline);
}
```
カスタム位置を設定するには、`--tt-area` を上書きします：
```css
.tooltip--right { --tt-area: inline-end; }
.tooltip--left { --tt-area: inline-start; }
.tooltip--bottom { --tt-area: block-end; }
```
自動切り替えなしで位置を固定するには：
```css
.tooltip--fixed-right {
--tt-area: inline-end;
--tt-fallbacks: none;
}
```
### プログラムによる表示
ホバーやフォーカスなしでツールチップを表示するには、`data-tooltip-visible` を追加します：
```html
```
## カスタマイズ
CSS 変数を上書きして外観を調整します：
| 変数 | デフォルト値 | 説明 |
| --- | --- | --- |
| `--tt-area` | `block-start` | アンカーを基準とした位置エリア |
| `--tt-fallbacks` | `flip-block, flip-inline` | クリップされた場合のフォールバック位置 |
| `--tt-gap` | `0.5rem` | アンカーとツールチップの間隔 |
| `--tt-bg` | `rgb(0 0 0 / 90%)` | 背景色 |
| `--tt-color` | `#fff` | テキスト色 |
| `--tt-size` | `0.875rem` | フォントサイズ |
| `--tt-padding` | `0.5em 0.75em` | バブルのパディング |
| `--tt-radius` | `0.25em` | 境界線の丸み |
| `--tt-shadow` | `none` | バブルの影（ボックスシャドウ） |
| `--tt-max-width` | `20rem` | バブルの最大幅 |
| `--tt-z-index` | `10` | 重なり順 (z-index) |
| `--tt-duration` | `0.2s` | トランジションの時間 |
| `--tt-ease` | `ease` | トランジションのタイミング関数 |
| `--tt-start` | `none` | 非表示状態の変形（例: `scale(0.85)`, `translateY(6px)`） |
| `--tt-end` | `none` | 表示状態の変形 |
例：
```css
.tooltip--custom {
--tt-bg: #2563eb;
--tt-color: #ffffff;
--tt-radius: 8px;
--tt-padding: 8px 12px;
--tt-shadow: 0 4px 12px rgb(0 0 0 / 15%);
--tt-gap: 0.5rem;
}
```
## コンパクトバージョン
CSS 変数を使用せず、できるだけ軽量にしたい場合のために、本プロジェクトにはコンパクト版（`compact.css` / `compact.min.css`）が含まれています。CSS Anchor Positioning による自動配置と、非対応ブラウザ向けのフォールバックをそのまま維持しています。
非常に軽量（非圧縮で約 1 KB、圧縮後で約 800 B）であるため、外部依存関係として読み込むのではなく、[compact.css](compact.css) のコードをプロジェクトのスタイルシートに直接コピーして組み込むことを推奨します。これにより、変数に頼ることなく CSS で直接ツールチップのスタイル全体をカスタマイズできます。
パッケージからインポートして使用することも可能です：
```js
import '@zkreations/tooltips/compact.min.css';
```
## 矢印なし、それが設計上の選択
v5 は擬似要素の矢印（`::after`）を含んでいません。`flip-block` および `flip-inline` はバブルの配置を変えますが、その方向の変化をすべてのブラウザで一貫して擬似要素の境界線に伝えることができず、視覚的なバグを引き起こします。矢印を省略することでそれらのバグを回避し、スタイルシートをより小さく保ちます。
## ブラウザ互換性
- CSS Anchor Positioning をサポートするブラウザは `@supports (position-area: block-start)` を使用して動的配置と自動切り替えを行います。
- 未対応のブラウザは静的なフォールバックを受け取ります：上部中央の絶対配置バブル。
- 現在のサポート状況：[Can I Use — CSS Anchor Positioning](https://caniuse.com/css-anchor-positioning)。
## v4 から v5 への移行
| v4 | v5 |
| --- | --- |
| `[data-tts]` | `.tooltip` |
| `data-tts-visible` | `data-tooltip-visible` |
| `[data-tts="down"]` | `--tt-area: block-end;` |
| `[data-tts="left"]` | `--tt-area: inline-start;` |
| `[data-tts="right"]` | `--tt-area: inline-end;` |
| `--tts-*` | `--tt-*` |
| `tooltips.min.css` | `index.min.css` |
## サポート
このプロジェクトの維持を支援したい場合は、[コーヒーをごちそうしてください](https://ko-fi.com/zkreations)。
## ライセンス
MIT ライセンス