Tailwind CSS Dark Mode Kullanımı: Sistem Tercihi, Sınıf ve data-theme

Varsayılan davranış: sistem tercihine göre

Hiçbir ayar yapmadan dark: önekini kullanabilirsiniz. Resmî dark mode sayfası bu varsayılanı prefers-color-scheme medya özelliğine bağlar. Aşağıdaki HTML'i derledik:

<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
  <a class="text-sky-700 dark:text-sky-300 dark:hover:text-sky-200" href="#">Devamı</a>
  <span class="md:dark:bg-gray-800"></span>
</div>

v4.3.5 ile derlenen CSS:

@layer utilities {
  .bg-white {
    background-color: var(--color-white);
  }
  .text-gray-900 {
    color: var(--color-gray-900);
  }
  .text-sky-700 {
    color: var(--color-sky-700);
  }
  @media (prefers-color-scheme: dark) {
    .dark\:bg-gray-900 {
      background-color: var(--color-gray-900);
    }
    .dark\:text-sky-300 {
      color: var(--color-sky-300);
    }
    .dark\:text-white {
      color: var(--color-white);
    }
    @media (hover: hover) {
      .dark\:hover\:text-sky-200:hover {
        color: var(--color-sky-200);
      }
    }
  }
  @media (width >= 48rem) {
    @media (prefers-color-scheme: dark) {
      .md\:dark\:bg-gray-800 {
        background-color: var(--color-gray-800);
      }
    }
  }
}

Çıktıdan üç sonuç çıkıyor. Birincisi, dark: sınıfları normal sınıflardan sonra ve bir medya sorgusunun içinde yer alır. Koyu tema etkin olduğunda .dark\:bg-gray-900 kuralı aynı özgüllükteki .bg-white kuralından sonra geldiği için kazanır; açık temada ise medya sorgusu hiç eşleşmez ve beyaz zemin kalır. İkincisi, varyantlar yığılabilir: dark:hover:text-sky-200 önce koyu tema sorgusuna, sonra (hover: hover) sorgusuna ve :hover sözde sınıfına sarılır. Üçüncüsü, sıralama okunduğu gibi uygulanır: md:dark: yazdığınızda dıştaki sorgu genişlik koşulu, içteki sorgu renk şeması olur. Hover varyantının ayrıntıları hover ve focus yazısında, kırılım noktaları responsive tasarım yazısında anlatılıyor.

Bu yöntemin artısı hiçbir JavaScript gerektirmemesidir; kullanıcı işletim sisteminde koyu temaya geçtiğinde site de geçer. Eksisi ise kullanıcının site içinde ayrı bir seçim yapamamasıdır. Kullanıcıya bir tema düğmesi sunmak istiyorsanız aşağıdaki yöntemlerden birine geçmeniz gerekir.

Sınıfla manuel kontrol: @custom-variant dark

Resmî belgenin önerdiği yol, dark varyantını CSS dosyanızda yeniden tanımlamaktır. Aşağıdaki satırı @import "tailwindcss"; satırının hemen altına eklersiniz:

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

Aynı HTML'i bu tanımla yeniden derlediğimizde medya sorguları kayboldu ve yerlerine seçiciler geldi:

@layer utilities {
  /* (kısaltıldı) */
  .dark\:bg-gray-900:where(.dark, .dark *) {
    background-color: var(--color-gray-900);
  }
  .dark\:text-sky-300:where(.dark, .dark *) {
    color: var(--color-sky-300);
  }
  .dark\:text-white:where(.dark, .dark *) {
    color: var(--color-white);
  }
  @media (hover: hover) {
    .dark\:hover\:text-sky-200:where(.dark, .dark *):hover {
      color: var(--color-sky-200);
    }
  }
  @media (width >= 48rem) {
    .md\:dark\:bg-gray-800:where(.dark, .dark *) {
      background-color: var(--color-gray-800);
    }
  }
}

Tanımdaki & işareti sınıfın kendisinin yerini tutar. :where(.dark, .dark *) ise iki durumu kapsar: elemanın kendisinde dark sınıfı varsa veya dark sınıflı bir atanın içindeyse. Pratikte <html class="dark"> yazdığınızda sayfadaki tüm dark: sınıfları etkinleşir; sınıfı kaldırdığınızda hepsi devre dışı kalır. Artık işletim sistemi tercihi doğrudan hiçbir şeyi değiştirmez; hangi temanın görüneceğine sizin betiğiniz karar verir.

<html class="dark">
  <body>
    <div class="bg-white dark:bg-black">
      <!-- ... -->
    </div>
  </body>
</html>

data-theme niteliğiyle kontrol

Sınıf yerine bir veri niteliği kullanmayı tercih ediyorsanız seçiciyi değiştirmeniz yeterli. Resmî sayfadaki örnek şöyledir:

@import "tailwindcss";
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

Derleme çıktısında seçici buna göre değişti: .dark\:bg-gray-900:where([data-theme=dark], [data-theme=dark] *). HTML tarafında <html data-theme="dark"> yazarsınız. Nitelik yaklaşımının pratik bir yararı, ileride "sepia" veya "yüksek kontrast" gibi ek temalar eklemek istediğinizde aynı niteliğin farklı değerlerini kullanabilmenizdir; her biri için ayrı bir @custom-variant tanımlarsınız. Kendi varyantlarınızı yazmanın genel kuralları custom variant yazısında anlatılıyor.

Üç seçenekli tema düğmesi: açık, koyu, sistem

Resmî belge, sınıf tabanlı yöntemi localStorage ve window.matchMedia() ile birleştirerek açık, koyu ve "sistem tercihine uy" seçeneklerini destekleyen kısa bir betik gösterir. Mantığı şudur: kullanıcı açıkça bir tema seçmişse o kullanılır; hiç seçmemişse işletim sisteminin tercihine bakılır. Aşağıdaki kod resmî örnekten uyarlanmıştır:

// Sayfa yüklenirken veya tema değişirken çalıştırın.
// Yanıp sönmeyi önlemek için head içinde satır içi eklemek en iyisidir.
document.documentElement.classList.toggle(
  "dark",
  localStorage.theme === "dark" ||
    (!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);

// Kullanıcı açık temayı seçtiğinde
localStorage.theme = "light";

// Kullanıcı koyu temayı seçtiğinde
localStorage.theme = "dark";

// Kullanıcı sistem tercihine dönmek istediğinde
localStorage.removeItem("theme");

Betiğin ilk bölümü classList.toggle() fonksiyonuna ikinci argüman olarak bir koşul verir: koşul doğruysa dark sınıfı eklenir, yanlışsa kaldırılır. Koşul, ya kayıtlı tercihin "dark" olmasını ya da hiç kayıt bulunmamasıyla birlikte sistemin koyu tema istemesini arar. Resmî örneğin yorum satırı önemli bir uyarı içerir: bu kod sayfa yüklenirken <head> içinde satır içi çalışmalıdır. Betik geç yüklenirse sayfa önce açık temada çizilir, ardından koyuya geçer ve kullanıcı kısa bir parlama görür. Belge ayrıca tercihin nasıl saklanacağının size kalmış olduğunu, örneğin sunucu tarafında bir veritabanında tutulup dark sınıfının sunucuda HTML'e yazılabileceğini belirtir.

Anlamsal renk belirteçleri: dark: yazmadan tema değiştirmek

Büyük projelerde her elemana bg-white dark:bg-gray-950 çifti yazmak zamanla yorucu hale gelir. Alternatif, "zemin" ve "yazı" gibi anlamsal renk adları tanımlayıp bunların değerini CSS değişkenleriyle tema başına değiştirmektir. Resmî renk sayfası, başka bir değişkene başvuran tema renkleri için @theme inline kullanımını gösterir. Aşağıdaki girişi derledik:

@import "tailwindcss" source(none);
@source inline("bg-zemin text-yazi bg-zemin/80");
@custom-variant dark (&:where(.dark, .dark *));
@theme inline {
  --color-zemin: var(--site-zemin);
  --color-yazi: var(--site-yazi);
}
:root {
  --site-zemin: var(--color-white);
  --site-yazi: var(--color-gray-900);
}
.dark {
  --site-zemin: var(--color-gray-950);
  --site-yazi: var(--color-gray-100);
}

v4.3.5 ile derlenen CSS:

@layer theme {
  :root, :host {
    /* (kısaltıldı) */
    --color-gray-100: oklch(96.7% 0.003 264.542);
    --color-gray-900: oklch(21% 0.034 264.665);
    --color-gray-950: oklch(13% 0.028 261.692);
    --color-white: #fff;
  }
}
@layer utilities {
  .bg-zemin {
    background-color: var(--site-zemin);
  }
  .bg-zemin\/80 {
    background-color: var(--site-zemin);
    @supports (color: color-mix(in lab, red, red)) {
      background-color: color-mix(in oklab, var(--site-zemin) 80%, transparent);
    }
  }
  .text-yazi {
    color: var(--site-yazi);
  }
}
:root {
  --site-zemin: var(--color-white);
  --site-yazi: var(--color-gray-900);
}
.dark {
  --site-zemin: var(--color-gray-950);
  --site-yazi: var(--color-gray-100);
}

inline anahtar kelimesi sayesinde sınıflar doğrudan var(--site-zemin) değerine başvurdu; ara bir --color-zemin değişkeni üretilmedi. Böylece .dark sınıfı eklendiğinde değişkenin değeri değişir ve bg-zemin kullanan her eleman yeni rengi alır. HTML'de tek bir dark: öneki yazmanıza gerek kalmaz. Saydamlık modifier'ı da çalışmaya devam eder. Bu yaklaşımın bir bedeli vardır: renk adları artık paletin tonlarını değil anlamı anlatır, dolayısıyla ekipteki herkesin hangi belirtecin nerede kullanılacağını bilmesi gerekir. @theme inline ile normal @theme arasındaki fark @theme direktifi yazısında ayrıntılı anlatılıyor.

Uygulamalı örnek: koyu temaya uyumlu bir bilgi kartı

Şimdi parçaları birleştirelim. Sınıf tabanlı tanımı kullanan bir projede, zemini, kenarlığı, başlığı ve açıklama metni ayrı ayrı koyu temaya uyarlanmış bir kart yazalım. Her açık tema rengi için bir dark: karşılığı veriyoruz:

<article class="rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-800 dark:bg-gray-900">
  <h3 class="text-gray-900 dark:text-white">Yedekleme tamamlandı</h3>
  <p class="text-gray-600 dark:text-gray-400">Son yedek 03:00'te alındı.</p>
</article>

v4.3.5 ile derlenen CSS (@custom-variant dark (&:where(.dark, .dark *)) tanımıyla):

@layer utilities {
  .rounded-lg {
    border-radius: var(--radius-lg);
  }
  .border {
    border-style: var(--tw-border-style);
    border-width: 1px;
  }
  .border-gray-200 {
    border-color: var(--color-gray-200);
  }
  .bg-white {
    background-color: var(--color-white);
  }
  .p-6 {
    padding: calc(var(--spacing) * 6);
  }
  .text-gray-600 {
    color: var(--color-gray-600);
  }
  .text-gray-900 {
    color: var(--color-gray-900);
  }
  .dark\:border-gray-800:where(.dark, .dark *) {
    border-color: var(--color-gray-800);
  }
  .dark\:bg-gray-900:where(.dark, .dark *) {
    background-color: var(--color-gray-900);
  }
  .dark\:text-gray-400:where(.dark, .dark *) {
    color: var(--color-gray-400);
  }
  .dark\:text-white:where(.dark, .dark *) {
    color: var(--color-white);
  }
}

Bu çıktıda tüm dark: kuralları utilities katmanının sonunda toplandı. Ek koşul :where() içine sarıldığı için seçicinin ağırlığı yine tek bir sınıf kadardır; koyu temada kazanmalarının sebebi daha sonra gelmeleridir. Bu yüzden dark: sınıfını HTML'de normal sınıftan önce ya da sonra yazmanız sonucu değiştirmez. Renk seçimine bakın: açık temada başlık 900, açıklama 600 tonundaydı; koyu temada başlık beyaza, açıklama 400 tonuna geçti. Kenarlık da 200'den 800'e çıktı. Paletin simetrik yapısı, açık temadaki her tonun koyu temada "aynı uzaklıkta" bir karşılığını bulmayı kolaylaştırır. Kart kalıplarının daha zengin örnekleri bileşen örnekleri yazısında var.

Sayfanın yalnızca bir bölümünü koyu yapmak

Sınıf tabanlı tanımın seçicisi .dark * parçasını içerdiği için dark sınıfını html yerine herhangi bir elemana da koyabilirsiniz. O zaman yalnızca o elemanın kendisi ve içindeki elemanlar koyu tema kurallarını alır. Örneğin açık temalı bir sayfada koyu zeminli bir altbilgi veya bir kod örneği kutusu istiyorsanız, o bölümü <footer class="dark"> ile sarmalamak yeterlidir; bileşenlerin dark: sınıfları zaten yazılıysa ek bir şey yapmanız gerekmez. Varsayılan medya sorgusu yönteminde ise böyle bir bölgesel kullanım mümkün değildir, çünkü koşul sayfanın tamamı için tek bir sistem tercihine bağlıdır.

Bu esnekliğin tersi de bilinmelidir: sayfa koyu temadayken içerideki bir bölümü açık temaya döndürmek için aynı tanım yetmez. html üzerindeki dark sınıfı tüm alt elemanları kapsadığı için bu tanım, içteki bir bölümün açık temaya dönmesine tek başına izin vermez. Böyle bir ihtiyaç varsa, anlamsal belirteçlerle o bölümde değişkenleri açık tema değerlerine geri çekmek daha temiz bir çözümdür.

dark: varyantı diğer durum varyantlarıyla da birleşir. dark:group-hover:text-white veya dark:focus-visible:ring-sky-400 gibi bir sınıf, önce koyu tema koşulunu, ardından grup veya odak koşulunu uygular. Grup ve peer varyantları group ve peer yazısında, erişilebilir odak halkaları erişilebilirlik yazısında anlatılıyor.

Hangi yöntemi seçmeli?

Tablodaki yöntemler birbirini dışlamaz, birlikte de kullanılabilirler. Anlamsal belirteçler, sınıf veya nitelik tabanlı varyantla birlikte kullanılır; bileşenlerin çoğu belirteçlerle boyanırken istisnai durumlar için yine dark: öneki yazılabilir.

Kendi CSS'inizde dark ve color-scheme sınıfları

Tailwind sınıfı kullanmadığınız bir kuralda da aynı dark tanımına bağlı kalmak isterseniz @variant dark bloğunu kullanabilirsiniz. Aşağıdaki kuralı sınıf tabanlı tanımla derledik:

@layer base {
  html { @variant dark { background-color: var(--color-gray-950); } }
}

@layer base {
  html:where(.dark, .dark *) {
    background-color: var(--color-gray-950);
  }
}

Derleyici bloğu, @custom-variant ile verdiğiniz seçiciye dönüştürdü. Tanımı ileride data-theme yöntemine çevirirseniz bu kural da otomatik olarak güncellenir. Tarayıcının kendi çizdiği kaydırma çubukları ve form denetimleri için color-scheme özelliğini ayarlayan sınıflar da vardır: scheme-light, scheme-dark ve scheme-light-dark. Derleme çıktısında bunlar sırasıyla color-scheme: light, color-scheme: dark ve color-scheme: light dark verdi; dark:scheme-dark yazdığınızda da kural :where(.dark, .dark *) seçicisiyle üretildi. Sınıf tabanlı bir temada <html class="dark:scheme-dark"> gibi bir kullanım, tarayıcı bileşenlerinin de koyu temaya uymasını sağlar.

Sık yapılan hatalar

• dark sınıfını ekleyip varyantı tanımlamamak: <html class="dark"> yazmak tek başına hiçbir şey değiştirmez. Varsayılan çıktıda kurallar @media (prefers-color-scheme: dark) içinde kalır; sınıfı dinlemesi için @custom-variant dark satırı şarttır.
• Seçicinin alt eleman kısmını unutmak: Tanımı &:where(.dark) diye kısaltırsanız derlenen kural .dark\:bg-black:where(.dark) olur. Bu yalnızca dark sınıfı elemanın kendisindeyse eşleşir; html üzerindeki sınıf alt elemanlara ulaşmaz.
• Betiği sayfanın sonuna koymak: Tema sınıfı ilk çizimden sonra eklenirse sayfa bir an açık temada görünür. Resmî örnek betiğin head içinde satır içi çalıştırılmasını önerir.
• Tek tarafı düşünmek: dark:text-white yazıp zemini unutmak, açık zemin üzerinde beyaz metne yol açar. Zemin ve metin rengini her zaman çift olarak düşünün ya da anlamsal belirteçlere geçin.
• Görselleri unutmak: Koyu temada fazla parlak kalan görseller için filtre sınıflarını (dark:brightness-90 gibi) değerlendirebilirsiniz; ayrıntı filtreler yazısında.

Sık Sorulan Sorular

Tailwind dark mode varsayılan olarak nasıl çalışır?

Ek ayar olmadan dark: varyantı işletim sisteminin renk şeması tercihine bakar; v4.3.5 çıktısında kurallar @media (prefers-color-scheme: dark) içinde üretildi.

Hem sistem tercihini hem de bir düğmeyi destekleyebilir miyim?

Evet. @custom-variant dark (&:where(.dark, .dark *)) tanımıyla sınıf tabanlı yönteme geçip resmî belgedeki betikle, kayıtlı tercih yoksa sistem tercihine düşen üç seçenekli bir yapı kurabilirsiniz.

v3'teki darkMode: "class" ayarı nereye gitti?

v4'te bu ayar JavaScript yapılandırma dosyasında değil, CSS içindeki @custom-variant satırında yapılır. Resmî dark mode sayfasında da yapılandırma dosyasından hiç söz edilmez; hem sınıf hem de nitelik yöntemi yalnızca CSS dosyanızdaki bu tek satırla kurulur. HTML'deki dark: sınıflarınızı değiştirmeniz gerekmez, yalnızca tanımın yeri değişir. Sürüm geçişinin diğer adımları için Tailwind v4 yenilikleri yazısına bakın.

Koyu tema için ayrı bir CSS dosyası gerekir mi?

Hayır. Derleyici dark: sınıflarını ayrı bir dosyaya değil, aynı çıktı dosyasına, normal sınıfların ardından yazar. Hangi yöntemi seçerseniz seçin tek bir CSS dosyası yüklersiniz; temalar arasındaki geçiş ya medya sorgusuyla ya da sizin eklediğiniz sınıf veya nitelikle tarayıcıda gerçekleşir. Yalnızca HTML'de gerçekten kullandığınız dark: sınıfları çıktıya girer, bu yüzden koyu tema desteği dosyayı yalnızca yazdığınız kadar büyütür.

dark: varyantını responsive sınıflarla birlikte kullanabilir miyim?

Evet. md:dark:bg-gray-800 gibi bir sınıf derlendiğinde genişlik sorgusunun içine dark koşulu yerleştirildi; her iki koşul da sağlandığında kural uygulanır.

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: Tailwind öğrenme rehberi · Renk paleti · Renk opaklığı · Custom variant · @theme direktifi · CSS dark mode