Yazılım

Filament Temalarını v4/v5’te Anlamak: Renklerden Özel CSS’e

Son güncelleme: 26 Haziran 2026 11:40

teknomers

Paylaş

Paylaş

Filament, admin panelinizin görünümünü ve hissini özelleştirmenize olanak tanıyan esnek bir temalandırma sistemi sunar. Bu kılavuz, Filament v4/v5 ile Tailwind CSS v4 kullanarak özel temalar oluşturma ve uygulama sürecini ele alacak.

<blockquote>
    <p>Bu kılavuz, <a href="https://filamentmastery.com/articles/customize-your-filament-panel-theme/" target="_blank" rel="noopener noreferrer">Filament v3 ve Tailwind v3</a> için yazılmış önceki bir kılavuzun güncellenmiş versiyonudur. Genel yaklaşım benzer olsa da, tema komutunun ürettiği içerik ve CSS sözdizimi, Tailwind v4'ün CSS-first yapılandırmasıyla değişmiştir. Hâlâ Filament v3 kullanıyorsanız, orijinal kılavuz burada mevcuttur.</p>
</blockquote>

<h2>
    <a name="setting-primary-colors-for-panels" href="#setting-primary-colors-for-panels"></a>
    Paneller için birincil renklerin ayarlanması
</h2>

<p>Tema dosyalarına dokunmadan önce, en basit özelleştirme, panelinizin renk paletini ayarlamaktır. Bu kısım değişmedi: Filament hâlâ <code>Filament\Support\Colors\Color</code> sınıfını kullanmaktadır.</p>

<p><strong>Seçenek 1: panellere göre renkleri tanımlama</strong></p>

<p>Panel sağlayıcınızda:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="kn">use</span> <span class="nc">Filament\Support\Colors\Color</span><span class="p">;</span>

public function panel(Panel $panel): Panel
{
return $panel
->colors([
‘danger’ => Color::Rose,
‘gray’ => Color::Gray,
‘info’ => Color::Blue,
‘primary’ => Color::Indigo,
<span class=”s1>’success’ => Color::Emerald,
<span class=”s1>’warning’ => Color::Orange,
]);
}

<p><strong>Seçenek 2: renkleri küresel olarak tanımlama</strong></p>

<p><code>AppServiceProvider</code> içerisinde, tüm paneller için uygulanması gereken:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="kn">use</span> <span class="nc">Filament\Facades\Filament</span><span class="p">;</span>

use Filament\Support\Colors\Color;

public function boot(): void
{
Filament::defaultColors([
<span class=”s1>’danger’ => Color::Rose,
<span class=”s1>’gray’ => Color::Gray,
<span class=”s1>’info’ => Color::Blue,
<span class=”s1>’primary’ => Color::Indigo,
<span class=”s1>’success’ => Color::Emerald,
<span class=”s1>’warning’ => Color::Orange,
]);
}

<p><strong>Burada durmak için doğru zaman:</strong> Hedefiniz yalnızca marka renklerini değiştirmekse, <code>-&gt;colors()</code> yeterlidir. Sadece yapılandırma UI değişiklikleri veya renk tokenlarının ulaşamayacağı arayüz parçalarının stilini değiştirmek için özel bir tema oluşturun.</p>

<h2>
    <a name="generating-the-theme" href="#generating-the-theme"></a>
    Temanın Oluşturulması
</h2>

<p>Komutun kendisi değişmedi:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>php artisan make:filament-theme</code></pre>
</div>

<p>Bir panel adı girmeniz istenecek (varsayılan: <code>admin</code>). Değişen, bu komutun sizin için ne ürettiği ve yaptığıdır.</p>

<p>Tailwind v4 kurulumunda, <code>member</code> paneli için çalıştırıldığında, o panele özel bir <code>theme.css</code> oluşturur:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight css"><code><span class="k">@import</span> <span class="s2">'../../../../vendor/filament/filament/resources/css/theme.css'</span><span class="p">;</span>

@source ‘../../../../app/Filament/Member/*/‘;
@source ‘../../../../resources/views/filament/member/*/‘;

<p>Gözlemleyin ki, <code>@source</code> yolları, genel <code>Filament/ /*</code> değil, yalnızca <code>Member</code> yönlendirmesini gösterir. Her panel kutudan çıkan kendi kapsama alanına sahip bir temaya sahip olur.</p>

<p>İşte bu kadar: oluşturulan dosya bilerek minimaldir. CSS değişkenleri veya açık/koyu geçişler için özel bir yer istiyorsanız, kendi <code>@layer base</code> bloğunuzu ekleyebilirsiniz:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight css"><code><span class="k">@layer</span> <span class="n">base</span> <span class="p">{</span>

<span class="nd">:root</span> <span class="p">{</span>

<span class="p">}</span>

<span class="nd">:root</span><span class="o">[</span><span class="nt">class</span><span class="o">~=</span><span class="s1">"dark"</span><span class="o">]</span> <span class="p">{</span>

<span class="p">}</span>

}

<p>Diğer önemli bir değişiklik: Filament v3'te, temayı <code>vite.config.js</code> dosyasına elle eklemeniz ve panel sağlayıcınızda <code>-&gt;viteTheme()</code> ile kaydetmeniz gerekiyordu. v4/v5'te, komut her şeyin otomatik olarak yapılmasını sağlar. Manuel bir bağlantıya gerek yoktur.</p>

<p>Tailwind v3 ile kıyaslandığında birkaç şey değişti:</p>

<p><strong>Artık <code>tailwind.config.js</code> yok.</strong>  Tailwind v4, temel tema özelleştirmeleri için <strong><code>tailwind.config.js</code></strong> dosyasına ihtiyaç duymuyor. CSS-first yapılandırmasına geçiş yapıldı. Tema için ayrı bir JS yapılandırma dosyası oluşturulmasına veya sürdürülmesine gerek kalmadı.</p>

<p><strong><code>@source</code> direktifleri, eski <code>content</code> dizisini değiştirdi.</strong>  Tailwind v4, bu yolları doğrudan CSS'ten tarar, böylece hangi dosyaların sınıf kullanımını araştıracağını bilmek için bunları JS yapılandırmasında ilan etme gereksinimi ortadan kalkar.</p>

<p><strong>Oluşturulan dosya bilerek minimaldir.</strong>  Sadece içe aktarma ve o panel için <code>@source</code> yolları. Kimseye otomatik olarak eklenmiş bir <code>@layer base</code> bloğu yoktur; bunu yalnızca gerekiyorsa kendiniz eklemeniz gerekir.</p>

<h3>
    <a name="adding-your-own-directories-to-source" href="#adding-your-own-directories-to-source"></a>
    @source'a kendi dizinlerinizi ekleme
</h3>

<p>Oluşturulan <code>@source</code> direktifleri yalnızca Filament'in kendi dosyalarını kapsamaktadır. Kaynaklarınız, bileşenleriniz veya <code>app/Filament</code> dışındaki herhangi bir şey varsayılan olarak taranmaz. Blade bileşenlerinde, Livewire bileşenlerinde veya özel görünümlerde Tailwind sınıflarını kullanıyorsanız, bu dizinleri kendiniz eklemeniz gerekir:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight css"><code><span class="k">@source</span> <span class="s2">'../../../../app/Filament/ /*'</span><span class="p">;</span>

@source ‘../../../../resources/views/filament//*’;
@source ‘../../../../resources/views/components/*/‘;
@source ‘../../../../resources/views/livewire//*’;
@source ‘../../../../app/Livewire/*/‘;

<p>Burada bir dizini eklemeyi unutursanız, Tailwind, sınıf kullanımını asla görmediği için bu sınıfları temizler, bu da üretimde stilin rastgele çalışmadığı anlamına gelir. Yeni yollar ekledikten sonra <code>npm run build</code> ile yeniden derleme yapın.</p>

<h2>
    <a name="what-gets-registered-automatically" href="#what-gets-registered-automatically"></a>
    Otomatik Olarak Ne Kaydedilir
</h2>

<p>Komut sizin için kaydı yönettiği için, <code>vite.config.js</code> yeni tema ile birlikte techizatlandırmadan sonra <code>make:filament-theme</code> çalıştırıldığına dair güncellenmiş olarak mevcut:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight javascript"><code>import { defineConfig } from 'vite';

import laravel from ‘laravel-vite-plugin’;
import tailwindcss from “@tailwindcss/vite”;

export default defineConfig({
plugins: [
laravel({
input: [
‘resources/css/app.css’,
‘resources/css/filament/admin/theme.css’,
‘resources/js/app.js’,
],
refresh: true,
}),
tailwindcss(),
],
});

<p>Ve panel sağlayıcınızda zaten tema kaydedilmiştir:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="o">-&gt;</span><span class="nf">viteTheme</span><span class="p">(</span><span class="s1>'resources/css/filament/admin/theme.css'</span><span class="p">)</span></code></pre>
</div>

<p>Manuel olarak bağlanacak hiçbir şey kalmadı. Tek yapmanız gereken komutu çalıştırmak ve her iki dosya sizinle güncellenmiş olur.</p>

<h2>
    <a name="multiple-panels-multiple-themes" href="#multiple-panels-multiple-themes"></a>
    Birden Fazla Panel, Birden Fazla Tema
</h2>

<p>Uygulamanızda birden fazla panel varsa, örneğin bir admin paneli ve bir üye paneli, her biri kendi tema dosyasını alır ve bağımsız olarak kaydedilir.</p>

<p><code>make:filament-theme</code> komutunu her panel için bir kez çalıştırın:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>php artisan make:filament-theme backend

php artisan make:filament-theme member

<p>Her çalışma, otomatik olarak <code>vite.config.js</code> dosyasına kendi temasını ekler ve eşleşen panel sağlayıcısında kaydeder. Hem girişlerin zaten yer aldığına dair şu şekilde bir yapı elde edersiniz:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nf">laravel</span><span class="p">({</span>
<span class="n">input</span><span class="o">:</span> <span class="p">[</span>
    <span class="s1>'resources/css/app.css'</span><span class="p">,</span>
    <span class="s1>'resources/css/filament/backend/theme.css'</span><span class="p">,</span>
    <span class="s1>'resources/css/filament/member/theme.css'</span><span class="p">,</span>
    <span class="s1>'resources/js/app.js'</span><span class="p">,</span>
<span class="p">],</span>
<span class="n">refresh</span><span class="o">:</span> <span class="kc>true</span><span class="p">,</span>

}),

// BackendPanelProvider
->id(<span class=”s1>’backend’)
->viteTheme(<span class=”s1>’resources/css/filament/backend/theme.css’)

// MemberPanelProvider
->id(<span class=”s1>’member’)
->viteTheme(<span class=”s1>’resources/css/filament/member/theme.css’)

<p>Her <code>theme.css</code>, varsayılan olarak kendi paneline özgü bir kapsama alanına sahiptir. <code>@source</code> direktifleri yalnızca o panelin dosyalarına işaret eder ve bir temayı özelleştirmek diğerini etkilemez. Bu, <a href="https://filamentmastery.com/articles/laravel-filament-multipanel-starter-build-your-app-fast/" target="_blank" rel="noopener noreferrer">Multipanel</a> ve <a href="https://filamentmastery.com/articles/laravel-filament-multi-tenant-starter-build-your-app-fast/" target="_blank" rel="noopener noreferrer">Multi-Tenant</a> başlangıçlarının kurulumu ile aynıdır: iki tema, boş ve kapsama alanı oluşturulmuş olarak ve her panelin gerektiğinde farklı bir şekilde stillendirilmesi için hazırdır.</p>

<p><strong>Pahalı bir temi paneller arasında paylaşma:</strong>  her panel için ayrı bir dosya üretmek zorunda değilsiniz. İki panel aynı görünümde olmalıysa, her iki panel sağlayıcısını da aynı tema dosyasına yönlendirebilirsiniz:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// BackendPanelProvider</span>

->viteTheme(<span class=”s1>’resources/css/filament/shared/theme.css’)

// MemberPanelProvider
->viteTheme(<span class=”s1>’resources/css/filament/shared/theme.css’)

<p>Yalnızca, paylaşılan dosyadaki <code>@source</code> yollarının her iki panel dizinini kapsadığından emin olun, çünkü tek bir üretilmiş tema yalnızca oluşturulduğu panel için kapsama sahiptir.</p>

<h2>
    <a name="reading-filaments-hook-classes" href="#reading-filaments-hook-classes"></a>
    Filament'in Hook Sınıflarını Okuma
</h2>

<p>Renklerin ötesine geçip özelleştirmeye başladığınızda, <a href="https://filamentphp.com/docs/5.x/styling/css-hooks?ref=filamentmastery.com#common-hook-class-abbreviations" target="_blank" rel="noopener noreferrer">Filament'in CSS sınıflarını</a> hedefleyeceksiniz. Bunlar, aşağıdaki yan menü örneği ve arayüzün her yerinde kullanılanlardır. Ayrıca tutarlı bir adlandırma kuralına sahiptirler:</p>

<ul>
    <li><code>fi</code> "Filament" için kısaltmadır.</li>
    <li><code>fi-ac</code> Aksiyonlar paketinden kullanılan sınıflardır.</li>
    <li><code>fi-fo</code> Formlar paketinden kullanılan sınıflardır.</li>
    <li><code>fi-in</code> Bilgi listeleri paketinden kullanılan sınıflardır.</li>
    <li><code>fi-no</code> Bildirimler paketinden kullanılan sınıflardır.</li>
    <li><code>fi-sc</code> Şema paketinden kullanılan sınıflardır.</li>
    <li><code>fi-ta</code> Tablolar paketinden kullanılan sınıflardır.</li>
    <li><code>fi-wi</code> Widget’lar paketinden kullanılan sınıflardır.</li>
    <li><code>btn</code> "buton" için kısaltmadır.</li>
    <li><code>col</code> "sütun" için kısaltmadır.</li>
    <li><code>ctn</code> "kapsayıcı" için kısaltmadır.</li>
    <li><code>wrp</code> "saracak" için kısaltmadır.</li>
</ul>

<p>Bu deseni bildiğinizde, hook sınıf adları her zaman geliştirme kaynağını karıştırmadan daha anlaşılır hale gelir.</p>

<p><strong>Hook sınıflarını pratikte bulmak:</strong> Adlandırma kuralı, bulduğunuz bir sınıfın ne anlama geldiğini gösterir, ancak öncelikle bulmanız gerekir. En hızlı yol:</p>

<ol>
    <li>Özelleştirmek istediğiniz panelde tarayıcı geliştirici araçlarınızı açın.</li>
    <li>Hedeflemek istediğiniz öğeyi inceleyin.</li>
    <li>Denetleyicide <code>fi-</code> ile başlayan sınıfları arayın.</li>
    <li>Bu sınıfı tema CSS’inizde kullanın.</li>
</ol>

<p>Bu, yalnızca adlandırma kuralına dayanarak tahmin yapmak yerine, tam olarak görmekte olduğunuz öğeyi hedeflemenin en güvenilir yoludur.</p>

<h2>
    <a name="customizing-your-theme" href="#customizing-your-theme"></a>
    Temanızı Özelleştirme
</h2>

<p>Tema kaydedildikten sonra, artık kendi stillerinizi doğrudan <code>theme.css</code> dosyasına ekleyebilirsiniz. Filament'in hook sınıfları, belirli arayüz parçalarını hedeflemenize olanak tanıyan <a href="https://filamentphp.com/docs/5.x/styling/overview?ref=filamentmastery.com" target="_blank" rel="noopener noreferrer">Filament belgelerinde</a> belgelenmiştir.</p>

<p>İşte yan menüyü özelleştirme örneği, orijinal v3 kılavuzunda aynı fikre dayanarak, yeni dosya yapısına uyarlama:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight css"><code><span class="k">@import</span> <span class="s2">'../../../../vendor/filament/filament/resources/css/theme.css'</span><span class="p">;</span>

@source ‘../../../../app/Filament/*/‘;
@source ‘../../../../resources/views/filament/*/‘;

.fi-sidebar {
@apply !bg-gray-500;

<span class="err">.fi-sidebar-header</span> <span class="err">{</span>
    <span class="err">.fi-icon-btn-icon</span> <span class="err">{</span>
        <span class="err">@apply</span> <span class="err">text-primary-500;</span>
    <span class="p">}</span>
<span class="err">}</span>

<span class="nc">.fi-sidebar-group-label</span><span class="o">,</span> <span class="nc">.fi-icon-btn-icon</span><span class="o">,</span> <span class="nc">.fi-sidebar-group-icon</span><span class="o">,</span> <span class="nc">.fi-sidebar-item-icon</span><span class="o">,</span> <span class="nc">.fi-sidebar-item-button</span><span class="o">,</span> <span class="nc">.fi-sidebar-item-label</span> <span class="p">{</span>
    <span class="err">@apply</span> <span class="err">text-white;</span>
<span class="p">}</span>

<span class="nc">.fi-sidebar-item-active</span> <span class="p">{</span>
    <span class="err">.fi-sidebar-item-button</span> <span class="err">{</span>
        <span class="err">@apply</span> <span class="err">bg-primary-500;</span>
    <span class="p">}</span>
<span class="err">}</span>

<span class="nc">.fi-sidebar-item</span><span class="o">,</span> <span class="nc">.fi-sidebar-item-button</span> <span class="p">{</span>
    <span class="err">:hover</span> <span class="err">{</span>
        <span class="err">@apply</span> <span class="py">hover</span><span class="p">:</span><span class="n">bg-primary-500</span><span class="p">;</span>
    <span class="p">}</span>
<span class="err">}</span>

<span class="nc">.fi-icon-btn</span> <span class="p">{</span>
    <span class="err">:hover</span> <span class="err">{</span>
        <span class="err">@apply</span> <span class="py">hover</span><span class="p">:</span><span class="n">text-primary-500</span><span class="p">;</span>
    <span class="p">}</span>
<span class="err">}</span>

<span class="nc">.fi-sidebar-nav-groups</span> <span class="p">{</span>
    <span class="err">@apply</span> <span class="err">gap-y-0;</span>
<span class="p">}</span>