CSS’e Document Picture-in-Picture Geldi: “Her Zaman Üstte” Web Widget’ları Nasıl Çalışır?

Document Picture-in-Picture API, bir web sayfasının içeriğini diğer tüm pencerelerin üstünde yüzen, bağımsız bir tarayıcı penceresine taşımayı sağlayan bir Web API’sidir. Bu pencereye video değil, herhangi bir HTML koyulabilir; kullanıcı sekmeyi değiştirse veya başka bir uygulamaya geçse bile widget ekranda kalır. “CSS’e geldi” tarafı ayrı bir gelişme: display-mode: picture-in-picture adlı yeni bir CSS medya sorgusu, bu yüzen pencerenin içeriğini doğrudan stil sayfasından hedeflemeyi mümkün kılıyor — ve bu özelliği Firefox da 2026’da desteklemeye başladı.

Document Picture-in-Picture API Nedir?

Klasik Picture-in-Picture yıllardır tarayıcılarda var, ama sadece <video> etiketiyle sınırlıydı. Document Picture-in-Picture API bu sınırı kaldırıyor: window.documentPictureInPicture.requestWindow() çağrısı, içine istediğiniz DOM elementini taşıyabileceğiniz ayrı bir pencere döndürüyor. Bu pencere birkaç kurala tabi:

• Her zaman üstte kalır, diğer pencereler tarafından örtülmez.
• Aynı kaynak (same-origin) politikasına bağlıdır, açan sayfadan bağımsız gezinemez (navigate edemez).
• Kullanıcı jesti (user gesture) gerektirir — sayfa yüklenir yüklenmez kendiliğinden açılamaz.
• Sekme başına tek pencereyle sınırlıdır ve açan pencereden daha uzun yaşayamaz.

Temel kullanım şöyle görünüyor:

if ("documentPictureInPicture" in window) {
  const pipWindow = await window.documentPictureInPicture.requestWindow({
    width: 320,
    height: 240,
  });

  // Herhangi bir elementi PiP penceresine taşı
  pipWindow.document.body.append(myWidget);

  // Pencere kapatıldığında elementi geri al
  pipWindow.addEventListener("pagehide", () => {
    mainContainer.append(myWidget);
  });
}

Bu API, Chrome 116 ile Ağustos 2023’te kullanıma açıldı. Kaynak: MDN — Document Picture-in-Picture API, Chrome for Developers — Picture-in-Picture for any Element.

CSS’e Tam Olarak Ne Geldi?

Document Picture-in-Picture penceresi açıldığında, içindeki sayfa normal sayfadan farklı davranmalı — daha küçük bir alanda, kontrolsüz bir çerçevede gösteriliyor. Bunu elle JavaScript ile yönetmek yerine CSS Working Group, display-mode: picture-in-picture adında yeni bir medya sorgusu değeri tanımladı. Bu değer Chrome 123’ten itibaren ve Chrome Platform Status kaydına göre kullanılabiliyor. Bu, sitede daha önce ele aldığımız CSS’e “Navigasyon Eşleştirme” Geliyor yazısındaki gibi, CSS’in tarayıcı davranışına doğrudan müdahale eden yeni bir sorgu tipi.

Kullanımı @media sorgusunun bir uzantısı kadar basit:

@media (display-mode: picture-in-picture) {
  body {
    margin: 0;
    padding: 8px;
    font-size: 0.85em;
  }

  .sadece-ana-sayfada {
    display: none;
  }
}

/* Renk şemasıyla birlikte kullanılabilir */
@media (display-mode: picture-in-picture) and (prefers-color-scheme: dark) {
  body {
    background: #111;
    color: #eee;
  }
}

Bu sayede tek bir stil sayfasını hem ana sayfaya hem de PiP penceresine bağlayıp içindeki farkları medya sorgusuyla ayırabilirsiniz — ayrı bir HTML dosyası veya inline stil kopyalamaya gerek kalmıyor. Kaynak: MDN — display-mode medya özelliği.

:picture-in-picture Pseudo-Class ile Karıştırmayın

CSS’te bir de :picture-in-picture pseudo-class’ı var ve isim benzerliği kafa karıştırabiliyor. Bu ikisi farklı şeyler:

• :picture-in-picture — klasik <video> PiP’inde, PiP moduna giren video elementini ana sayfada seçmek için kullanılır (video:picture-in-picture { ... }). Document Picture-in-Picture penceresine taşınan elementlere uygulanmaz.
• display-mode: picture-in-picture — Document Picture-in-Picture penceresinin içindeki belgeyi hedefler.

Kaynak: MDN — :picture-in-picture pseudo-class.

Tarayıcı Desteği: Kim Destekliyor, Kim Desteklemiyor?

Bu iki özelliğin desteği birbirinden farklı ilerliyor, o yüzden ayrı ayrı bakmak gerekiyor.

• Document Picture-in-Picture API (requestWindow()): Chrome/Edge 116+, Firefox 151+ (masaüstü).
• display-mode: picture-in-picture medya sorgusu: Chrome/Edge 123+, Firefox 151+.
• Safari: her iki özellik de desteklenmiyor.

Firefox 151, 19 Mayıs 2026’da yayınlandı ve Document Picture-in-Picture’ı masaüstünde varsayılan olarak etkinleştirdi. Kaynak: MDN — Firefox 151 sürüm notları ve Firefox bug 2006594. Sürüm numaraları için ayrıca Can I Use kaydına bakabilirsiniz.

Pratikte bu, kullanıcılarınızın büyük çoğunluğunun Chrome/Edge tabanlı bir tarayıcıda olacağı, Firefox kullanıcılarının 2026 ortasından beri bu deneyime dahil olduğu, Safari kullanıcıları için ise özelliğin hâlâ bulunmadığı anlamına geliyor. "documentPictureInPicture" in window ile özelliği önce algılayıp yoksa normal akışa devam etmek burada zorunlu bir adım.

Normal Pencere ile Document PiP Penceresi Arasındaki Fark

Document PiP penceresi, bir iframe ya da popup değil; işletim sisteminin kendi pencere yöneticisine ait, çerçevesiz ve her zaman üstte kalan ayrı bir üst düzey pencere. Ana sayfa arka planda normal akışına devam ederken, taşınan element artık DOM’da PiP penceresinin document‘ine ait.

Bu, elementin aynı JavaScript state’ini koruduğu anlamına geliyor — bir video oynatıcıyı taşıdığınızda oynatma pozisyonu sıfırlanmaz, bir sayaç taşındığında sayma durmaz. Kapandığında (pagehide event’i ile) elementi ana sayfaya geri eklemek geliştiricinin sorumluluğunda.

Nasıl Kullanılır? Adım Adım Kod Örneği

Uygulama akışı özetle dört adımdan oluşuyor:

1. Özellik tespiti — "documentPictureInPicture" in window ile API’nin var olup olmadığını kontrol edin.
2. Pencereyi açma — kullanıcı bir butona tıkladığında requestWindow({ width, height }) çağırın.
3. İçeriği taşıma ve stil kopyalama — pipWindow.document.body.append(element) ile elementi taşıyın, stil sayfalarını (document.styleSheets) PiP penceresine kopyalayın.
4. Kapanışı dinleme — pagehide event’inde elementi ana sayfaya geri döndürün.

async function pipAc() {
  if (window.documentPictureInPicture.window) return;

  const pipWindow = await window.documentPictureInPicture.requestWindow({
    width: 300,
    height: 200,
  });

  // Mevcut stil sayfalarını PiP penceresine kopyala
  [...document.styleSheets].forEach((sheet) => {
    try {
      const css = [...sheet.cssRules].map((r) => r.cssText).join("");
      const style = document.createElement("style");
      style.textContent = css;
      pipWindow.document.head.append(style);
    } catch (e) {
      const link = document.createElement("link");
      link.rel = "stylesheet";
      link.href = sheet.href;
      pipWindow.document.head.append(link);
    }
  });

  pipWindow.document.body.append(widget);

  pipWindow.addEventListener("pagehide", () => {
    anaKapsayici.append(widget);
  });
}

Kaynak: MDN — Document Picture-in-Picture API’yi kullanma kılavuzu.

Hangi Widget’lar İçin Mantıklı?

Bu API her şeye uygun değil — kullanıcının sekme değiştirdiğinde de takip etmesi gereken, canlı ve kısa ömürlü içerikler için anlamlı:

• Video konferans — katılımcı görüntülerini ve sohbet kutusunu, kullanıcı başka bir sekmede not alırken görünür tutmak.
• Özel video oynatıcılar — altyazı, oynatma listesi gibi özel kontrolleri korumak (tarayıcının varsayılan video PiP’inden farklı olarak tam kontrol sizde).
• Zamanlayıcı / geri sayım — bir Pomodoro sayacı veya canlı yayın geri sayımı.
• Borsa/veri ticker’ı — sürekli güncellenen sayısal bir gösterge.

Statik içerikler (bir makale, bir form) için PiP bir kazanç sağlamıyor; kullanıcı zaten sekmeler arasında geçiş yapabiliyor. Bu tür küçük ama etkili CSS/tarayıcı detaylarını sitede düzenli işliyoruz — örneğin CSS’e Gap Decorations Geldi yazısında grid ve flex’te ayraç çizgisi çekmenin yeni yolunu ele almıştık.

Kısıtlamalar ve Dikkat Edilmesi Gerekenler

• Konum kontrolü yok — pencerenin ekrandaki yerini web sitesi belirleyemez, tarayıcı/işletim sistemi karar verir.
• Navigasyon yok — PiP penceresi başka bir URL’ye gidemez, sadece açan sayfanın DOM’undan taşınan içeriği gösterir.
• HTTPS zorunlu — güvenli bağlam (secure context) gerektirir.
• Mobil desteği yok — hem Chrome hem Firefox tarafında şu an yalnızca masaüstü platformlarda çalışıyor.
• Polyfill yok — bu tarayıcı düzeyinde bir pencere yönetimi özelliği olduğundan JavaScript ile taklit edilemiyor; desteklenmeyen tarayıcılarda tek seçenek özelliği gizleyip normal akışa dönmek.

Safari’nin CSS tarafında henüz desteklemediği başka bir platform detayını da iOS Safari’de Site Arka Planını Çentiğin Altına Uzatan CSS Hilesi yazısında incelemiştik.

Sık Sorulan Sorular

Document Picture-in-Picture Safari’de çalışıyor mu?
Hayır. Bu yazının hazırlandığı tarih itibarıyla Safari, Document Picture-in-Picture API’yi ve display-mode: picture-in-picture CSS medya sorgusunu desteklemiyor. Klasik <video> PiP’i (Safari 13.1’den beri) ayrı bir özellik ve bu durumdan etkilenmiyor.

Document Picture-in-Picture için polyfill var mı?
Hayır. Bu, tarayıcının kendi pencere yöneticisini kullanan bir özellik olduğu için JavaScript ile taklit edilemiyor. Desteklenmeyen tarayıcılarda yapılabilecek tek şey "documentPictureInPicture" in window ile özelliği algılayıp arayüzden gizlemek.

:picture-in-picture pseudo-class’ı Document PiP penceremi stillemek için kullanabilir miyim?
Hayır. :picture-in-picture yalnızca klasik <video> PiP’inde PiP moduna giren video elementini hedefler. Document PiP penceresinin içeriğini stillemek için @media (display-mode: picture-in-picture) medya sorgusunu kullanmanız gerekiyor.

Document Picture-in-Picture penceresini kullanıcı fark etmeden otomatik açabilir miyim?
Hayır. API, requestWindow() çağrısının bir kullanıcı jesti (tıklama gibi) sonrasında yapılmasını zorunlu kılıyor; sayfa yüklenirken veya arka planda kendiliğinden açılamıyor.

Firefox’ta Document Picture-in-Picture’ı etkinleştirmek için ayar değiştirmek gerekiyor mu?
Hayır. Firefox 151’den itibaren özellik masaüstünde varsayılan olarak açık geliyor, ayrıca bir bayrak (flag) etkinleştirmeye gerek yok.