useTemplateRef() テンプレート ref を取得する（3.5+ の推奨書き方）
最終更新：2026-10-22
useTemplateRef() テンプレート ref を取得する（3.5+ の推奨書き方）
useTemplateRef() は文字列のキーで同名の ref 属性のテンプレート参照を取得します。「同じ名前の変数を宣言する」というボイラープレートが不要になります。
| グループ | テンプレートとヘルパー |
|---|---|
| 種類 | API |
| スコープ | コンポーネント内 |
| Vue バージョン | 3.5+ |
| SSR 対応 | 対応 |
📝 構文
const inputEl = useTemplateRef('my-input')
// テンプレート：<input ref="my-input">⚙️ 引数
| key | テンプレートの ref 属性値と一致する文字列 |
|---|
戻り値：読み取り専用の ref。マウント前は null
▶ 例
以下のコードを編集して結果を確認しましょう：
出力：
Clicking focuses the input.💡 ポイント
💡 ヒント 3.5 以降の推奨書き方です。従来の書き方（同名の ref 変数 + 自動収集）もそのまま使えます。
⚠️ 注意 マウント前は null です。アクセス前に null チェックするか、onMounted 以降で使ってください。
ℹ️ 補足 v-for の中ではコンポーネント / 要素の配列になります。
🏷️ 関連テンプレートとヘルパー
💡 関連ケース
関連ケースは近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q 同名の ref 変数を直接宣言するのと何が違いますか？
A 機能は同じです。useTemplateRef は同名の縛りがなく意味も明確なので、複数の参照を扱う場面に向いています。
Q 子コンポーネントのインスタンスを取得できますか？
A 取得できます。コンポーネントインスタンスを指します。そのメソッドを呼ぶには、子コンポーネント側で defineExpose で公開してください。
Q 3.5 未満ではどうしますか？
A 従来の書き方を使ってください。const txt = ref(null) とし、テンプレートで ref="txt" と書きます（コンパイル時に自動収集）。
