shadcn/ui Popover, Tooltip ve Hover Card: Ne Zaman Hangisi?

Popover: tıklayınca açılan zengin katman

shadcn/ui: Popover sayfası bileşeni, bir düğmeyle tetiklenen ve zengin içeriği bir portal içinde gösteren katman olarak tanımlar. Bileşen Radix UI: Popover ilkeline dayanır. CLI ile kurulum components/ui/popover.tsx dosyasını oluşturur; elle kurulumda @radix-ui/react-popover paketini yüklersiniz.

npx shadcn@latest add popover
npm install @radix-ui/react-popover

İlk satır CLI kurulumudur, ikincisi yalnızca elle kurulumda gereken bağımlılıktır. Dosya dört parça dışa aktarır: Popover kök bileşen, PopoverTrigger tetikleyici, PopoverContent içerik kutusu ve PopoverAnchor. Sonuncusu, katmanı tetikleyiciden farklı bir öğeye hizalamak istediğinizde kullanılan Radix çapa parçasının sarmalayıcısıdır; belge sayfası ayrıca örnek vermez.

Kaynak koda göre PopoverContent iki varsayılan taşır: align="center" ve sideOffset={4}, yani katman tetikleyiciye ortalanır ve ondan 4 piksel uzakta açılır. Kutunun varsayılan genişliği w-72, iç boşluğu p-4'tür; arka plan ve yazı rengi tema değişkenlerinden bg-popover ve text-popover-foreground olarak gelir. Bu renk çiftinin nereden geldiğini tema ve CSS değişkenleri yazısında bulabilirsiniz.

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover"

export function BoyutAyari() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="outline">Boyutları ayarla</Button>
      </PopoverTrigger>
      <PopoverContent className="w-80">
        <div className="grid gap-4">
          <div className="space-y-2">
            <h4 className="leading-none font-medium">Boyutlar</h4>
            <p className="text-muted-foreground text-sm">
              Katmanın genişliğini belirleyin.
            </p>
          </div>
          <div className="grid grid-cols-3 items-center gap-4">
            <Label htmlFor="width">Genişlik</Label>
            <Input id="width" defaultValue="100%" className="col-span-2 h-8" />
          </div>
        </div>
      </PopoverContent>
    </Popover>
  )
}

Bu örnek belgedeki demo dosyasının kısaltılmış halidir: düğmeye basıldığında altında, içinde başlık, açıklama ve etiketli bir metin kutusu bulunan bir katman açılır. Genişlik className="w-80" ile varsayılandan biraz büyütülmüştür. Popover'ın içine form öğeleri koyabilmeniz, onu Tooltip'ten ayıran temel özelliktir.

Konum öznitelikleri ve animasyon

Üç bileşen de aynı animasyon yaklaşımını paylaşır. Radix, katmanın tetikleyicinin hangi tarafında açıldığını data-side özniteliğine yazar; kaynak koddaki data-[side=bottom]:slide-in-from-top-2 gibi sınıflar bu değere göre katmanı doğru yönden kaydırarak getirir. Alttan açılan bir katman yukarıdan, sağdan açılan bir katman soldan kayar. Büyüme efektinin merkezi de Radix'in verdiği bir CSS değişkeninden alınır: Popover'da --radix-popover-content-transform-origin, Tooltip'te --radix-tooltip-content-transform-origin, Hover Card'da --radix-hover-card-content-transform-origin. Böylece katman, tetikleyiciye en yakın noktadan büyüyormuş gibi görünür.

Üç içerik bileşeni de kendini bir portal içinde çizer ve z-50 katman sırasını kullanır. Portal sayesinde katman, overflow-hidden sınıflı bir kartın ya da kaydırılabilir bir tablonun içinde olsa bile kesilmeden görünür. Kendi bileşenlerinizde daha yüksek bir katman sırası kullanıyorsanız, katmanın onların altında kalmaması için bu değeri hesaba katın.

Popover'ı başka bileşenlerle birleştirmek

Popover, shadcn/ui'daki birçok kalıbın taşıyıcısıdır. Date Picker bir Popover içine Calendar koyar; aranabilir seçim kutusu (combobox) bir Popover içine Command koyar. Bu birleşimlerde içerik kutusu genellikle w-auto p-0 ya da w-[200px] p-0 gibi sınıflarla kendi boşluğundan arındırılır, çünkü iç bileşen kendi boşluğunu getirir. Kapanmayı kodla yönetmek gerektiğinde kök bileşene open ve onOpenChange verilir; doğum tarihi seçici bloğu gün seçildiğinde setOpen(false) çağırarak katmanı kapatır. Ayrıntılar için Calendar ve Date Picker ile Combobox yazılarına bakın.

Konumlandırma için Radix'in side ve align prop'ları kullanılır. Depodaki combobox örneklerinden biri katmanı tetikleyicinin sağında açmak için side="right" align="start" verir; metin kutulu tarih seçici ise align="end", alignOffset={-8} ve sideOffset={10} ile katmanı ince ayarla yerleştirir. Button Group örneğinde bir açılır ok düğmesi Popover tetikleyicisi olarak kullanılır ve içerik align="end" ile grubun sağ kenarına hizalanır; bu kalıp Button Group yazısında anlatılıyor.

Tooltip: odak ya da fareyle açılan kısa bilgi

shadcn/ui: Tooltip sayfası bileşeni, bir öğe klavye odağı aldığında ya da fare üstüne geldiğinde o öğeyle ilgili bilgi gösteren bir açılır katman olarak tanımlar. Bileşen Radix UI: Tooltip ilkeline dayanır ve elle kurulumda @radix-ui/react-tooltip paketi gerekir.

npx shadcn@latest add tooltip

import { Button } from "@/components/ui/button"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export function KutuphaneyeEkle() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Button variant="outline">Ekle</Button>
      </TooltipTrigger>
      <TooltipContent>
        <p>Kütüphaneye ekle</p>
      </TooltipContent>
    </Tooltip>
  )
}

Fare düğmenin üstüne geldiğinde ya da düğme Tab tuşuyla odak aldığında, düğmenin yanında küçük, koyu zeminli bir etiket ve ona bağlı küçük bir ok görünür. İçerikteki p etiketi belgedeki örnekten gelir; kısa bir metin için doğrudan düz yazı da koyabilirsiniz. İpucu metnini bir iki kelimeyle sınırlı tutmak, katmanın öğeyi kapatmasını önler.

TooltipProvider gerekli mi?

Radix Tooltip normalde bir Provider bileşeni ister. Depodaki tooltip.tsx kaynağına bakınca shadcn/ui'ın bunu sizin yerinize çözdüğünü görürsünüz: Tooltip bileşeni her kullanımda kendi TooltipProvider sarmalayıcısını oluşturur ve bu sarmalayıcı delayDuration değerini varsayılan olarak 0 yapar. Bu yüzden belgedeki kullanım örneğinde ayrı bir Provider görmezsiniz ve ipucu beklemeden açılır. Dosya TooltipProvider bileşenini ayrıca da dışa aktarır; gecikme gibi ayarları kendiniz vermek isterseniz bu bileşeni ya da Radix'in kök bileşen prop'larını kullanabilirsiniz. Ayrıntılı seçenekler belgede bağlantısı verilen Radix sayfasındadır.

Renkler ve 2025-09-22 değişikliği

Tooltip sayfasının değişiklik kaydı, 22 Eylül 2025 tarihli bir renk güncellemesini anlatır: ipucu artık arka plan için ön plan rengini, yazı için arka plan rengini kullanır. Eski bir kopyanız varsa TooltipContent ve TooltipArrow içindeki bg-primary text-primary-foreground sınıflarını bg-foreground text-background ile değiştirmeniz istenir. Depodaki güncel kaynakta içerik kutusu bg-foreground text-background sınıflarını, ok da bg-foreground fill-foreground sınıflarını taşır. Sonuç olarak açık temada koyu, koyu temada açık bir ipucu görürsünüz.

Kaynaktaki diğer varsayılanlar da bilinmeye değer: TooltipContent bileşeninde sideOffset varsayılanı 0'dır, yazı text-xs boyutundadır ve kutu genişliği içeriğe göre (w-fit) ayarlanır. Katmanın yönünü side prop'u ile değiştirebilirsiniz; depodaki Input Group örneği yardım simgesindeki ipucunu side="left" ile sola açar.

Simge düğmelerinde ipucu ve klavye kısayolu

İpucunun en yaygın kullanımı, yalnızca simgeden oluşan düğmelerin ne yaptığını anlatmaktır. Depodaki Input Group örneğinde yardım düğmesi hem bir Tooltip ile sarılır hem de aria-label="Help" özniteliği taşır. Bu ikisi birbirinin yerine geçmez: ipucu görsel bir açıklamadır, aria-label ise düğmenin erişilebilir adıdır. Aynı örnek tetikleyicinin her zaman bir Button olmak zorunda olmadığını da gösterir: TooltipTrigger asChild burada bir InputGroupAddon parçasını sarar ve ipucu metin kutusunun yanındaki yardım alanına bağlanır. Input Group parçaları Input, Textarea ve Input Group yazısında anlatılıyor. Ekim 2025'te eklenen Kbd bileşeni de ipucu içinde kısayol göstermek için kullanılabilir; Kbd sayfasındaki örnekte "Kaydet" düğmesinin ipucunda bir tuş etiketi yer alır.

import { Button } from "@/components/ui/button"
import { Kbd } from "@/components/ui/kbd"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export function KaydetIpucu() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Button size="sm" variant="outline">
          Kaydet
        </Button>
      </TooltipTrigger>
      <TooltipContent>
        <div className="flex items-center gap-2">
          Değişiklikleri kaydet <Kbd>S</Kbd>
        </div>
      </TooltipContent>
    </Tooltip>
  )
}

Bu örnek için kbd bileşenini de eklemeniz gerekir; ayrıntılar Item, Empty, Kbd ve Avatar yazısında. Kbd yalnızca tuşu gösterir; kısayolun gerçekten çalışması için klavye olayını kendiniz dinlemelisiniz.

Hover Card: bağlantının arkasındaki içeriğe önizleme

shadcn/ui: Hover Card sayfası bileşeni çok kısa bir cümleyle tanımlar: görebilen kullanıcıların bir bağlantının arkasındaki içeriği önizlemesi içindir. Bileşen Radix UI: Hover Card ilkeline dayanır; elle kurulumda @radix-ui/react-hover-card paketi yüklenir. Parçalar HoverCard, HoverCardTrigger ve HoverCardContent'tir.

npx shadcn@latest add hover-card

Belgedeki örnek bir kullanıcı adı bağlantısının üzerine gelindiğinde profil kartı gösterir: tetikleyici link varyantlı bir Button, içerik ise avatar, başlık, kısa açıklama ve katılım tarihinden oluşan bir kutudur.

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@/components/ui/avatar"
import { Button } from "@/components/ui/button"
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@/components/ui/hover-card"

export function ProfilOnizleme() {
  return (
    <HoverCard>
      <HoverCardTrigger asChild>
        <Button variant="link">@nextjs</Button>
      </HoverCardTrigger>
      <HoverCardContent className="w-80">
        <div className="flex justify-between gap-4">
          <Avatar>
            <AvatarImage src="https://github.com/vercel.png" />
            <AvatarFallback>VC</AvatarFallback>
          </Avatar>
          <div className="space-y-1">
            <h4 className="text-sm font-semibold">@nextjs</h4>
            <p className="text-sm">Vercel tarafından geliştirilen React çatısı.</p>
            <div className="text-muted-foreground text-xs">Aralık 2021'den beri üye</div>
          </div>
        </div>
      </HoverCardContent>
    </HoverCard>
  )
}

Kaynak koda göre HoverCardContent de Popover gibi align="center" ve sideOffset={4} varsayılanlarını taşır; farkı varsayılan genişliğin w-64 olmasıdır. Görsel olarak Popover'a çok benzer, ama açılma biçimi farklıdır: Popover tıklamayla, Hover Card fareyle üzerine gelmeyle açılır.

Belgedeki örnekte tetikleyici yalnızca bağlantı görünümlü bir düğmedir ve bir yere gitmez. Bileşenin tanımı "bir bağlantının arkasındaki içerik" olduğu için gerçek bir projede tetikleyicinin gerçekten o sayfaya giden bir bağlantı olması daha anlamlıdır. Böylece önizlemeyi göremeyen kullanıcı da bağlantıya tıklayarak aynı içeriğe ulaşır. Button bileşeninin asChild ile bir bağlantıya dönüştürülmesi Button varyantları yazısında anlatılıyor.

Hangisini ne zaman kullanmalı?

Bu tablodan çıkan pratik kural şudur: kullanıcı katmanın içinde bir şey yapacaksa Popover; yalnızca bir öğenin ne olduğunu kısaca öğrenecekse Tooltip; bir bağlantıya tıklamadan önce hedefin özetini görmesi işine yarayacaksa Hover Card. Hover Card'ın tanımındaki "görebilen kullanıcılar" ifadesi önemli bir ipucudur: önizlemedeki bilgi tek başına kritik olmamalı, bağlantının gittiği sayfada da bulunmalıdır. Aynı mantıkla, Tooltip içine tıklanması gereken düğmeler koymak yerine Popover kullanın. Erişilebilirlik kavramlarının genel çerçevesi için ARIA rol ve öznitelikleri ve WCAG temelleri yazılarına bakabilirsiniz.

Sık yapılan hatalar

• Tetikleyicide asChild unutmak: <TooltipTrigger> ya da <PopoverTrigger> içine doğrudan bir Button koymak iç içe iki düğme üretir. Kendi düğmenizi kullanıyorsanız asChild verin.
• Simge düğmesinde yalnızca ipucuna güvenmek: ipucu görsel bir açıklamadır; düğmenin erişilebilir adı için örneklerdeki gibi aria-label ekleyin.
• Tooltip içine etkileşimli içerik koymak: belge Tooltip'i bilgi göstermek için tanımlar. Düğme, form ya da bağlantı içeren katmanlar için Popover seçin.
• Takvim ya da komut listesini varsayılan boşlukla açmak: PopoverContent varsayılan olarak w-72 p-4 gelir; iç bileşen kendi boşluğunu getiriyorsa w-auto p-0 verin.
• Eski tooltip renklerini korumak: 2025-09-22 değişikliğinden önceki bir kopya bg-primary kullanır; güncel görünüm için sınıfları değiştirin.
• Hover Card'a kritik bilgi koymak: belgeye göre bileşen görebilen kullanıcılar içindir; dokunmatik ekranda ya da klavyeyle gezinen kullanıcı aynı bilgiye başka bir yoldan ulaşabilmelidir.

Sık Sorulan Sorular

Tooltip için uygulamayı TooltipProvider ile sarmam gerekiyor mu?

Depodaki güncel tooltip.tsx kaynağında Tooltip kendi Provider'ını oluşturur, bu yüzden belgedeki kullanım örneği Provider olmadan çalışacak biçimde yazılmıştır. Eski bir kopyanız varsa dosyanızın içine bakın.

Popover'ı seçimden sonra nasıl kapatırım?

Kök bileşene open ve onOpenChange verip durumu kendiniz tutun; seçim olayında durumu false yapın. Doğum tarihi seçici ve combobox örnekleri bu yöntemi kullanır.

Popover ile Hover Card arasındaki fark nedir?

Görünümleri neredeyse aynıdır, ikisi de bg-popover renkli, kenarlıklı bir kutudur. Fark açılma biçiminde ve amaçtadır: Popover tıklamayla açılır ve etkileşimli içerik taşır, Hover Card fareyle üzerine gelindiğinde bir bağlantının önizlemesini gösterir.

Tooltip neden beklemeden açılıyor?

Kaynaktaki TooltipProvider sarmalayıcısı delayDuration değerini varsayılan olarak 0 yapar. Farklı bir gecikme istiyorsanız bu değeri kendi dosyanızda değiştirebilirsiniz.

Bu bileşenleri Next.js Server Component içinde kullanabilir miyim?

popover.tsx, tooltip.tsx ve hover-card.tsx dosyalarının ilk satırı "use client"'tır, yani üçü de istemci bileşenidir. Açık durumunu useState ile yöneten kendi bileşeninizin dosyasına da bu satırı eklemelisiniz. Kurulumun Next.js tarafı shadcn/ui Next.js kurulumu yazısında anlatılıyor.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: shadcn/ui öğrenme rehberi · Calendar ve Date Picker · Combobox · Item, Empty, Kbd ve Avatar · Dialog ve Alert Dialog · ARIA rol ve öznitelikleri