Templates

Every page in the admin interface is a Jinja2 template you can override. Whether you need to customize a single list page, a specific field's table cell, or a dashboard widget, you can apply your changes without forking the built-in template tree.

How the Template Loader Works

from sqlalchemy import create_engine
from starlette_admin.contrib.sqla import Admin

engine = create_engine("sqlite:///admin.sqlite")
admin = Admin(engine, title="My Admin", templates_dir="my_templates/")

The Admin class builds a Jinja2 ChoiceLoader that evaluates paths in a specific order: it checks your templates_dir first, followed by the built-in starlette_admin/templates/ package directory. If you place a file under my_templates/ using the exact relative path it has inside starlette_admin/templates/, your file shadows the built-in version. All other templates will continue to render from the built-in directory.

Template Directory Map

Overriding a Single Page Template

my_templates/
└── list.html   ← shadows the built-in list.html

{# my_templates/list.html #}
{% extends "@starlette-admin/list.html" %}

{% block content %}
  <div class="alert alert-info">Custom banner above the list.</div>
  {{ super() }}
{% endblock %}

Using {% extends "list.html" %} directly would resolve back to your custom my_templates/list.html because the templates_dir is checked first. This circular reference causes an infinite recursion error. The @starlette-admin/ prefix always points to the built-in copy. Therefore, any extends or include statements inside an override must use this prefix instead of the bare filename.

Overridable Blocks

Every built-in page extends layout.html, which in turn extends base.html. By overriding a specific {% block %} instead of an entire file, you can customize a specific fragment without duplicating the rest of the page's code:

{# my_templates/list.html #}
{% extends "@starlette-admin/list.html" %}

{% block list_toolbar_extra %}
  {{ super() }}
  <a class="btn btn-outline-primary" href="/reports/export">Custom report</a>
{% endblock %}

base.html

layout.html

list.html

detail.html

create.html / edit.html

login.html

index.html

error.html

Example: Replacing the Sidebar Logo with an Inline SVG

Passing a URL to Admin(logo_url=...) is the quickest way to set a logo and covers most use cases, including linking to external .svg files. However, the built-in template renders this URL inside a standard <img> tag, which restricts the SVG from inheriting CSS properties from the surrounding page.

When to use this approach: Override the brand block to inject inline <svg> markup when you need the logo to dynamically interact with the UI.

Implementation

Create a layout.html file in your custom templates directory. Since every page in the admin interface inherits from layout.html, this single override applies sitewide.

{# my_templates/layout.html #}
{% extends "@starlette-admin/layout.html" %}

{% block brand %}
  <svg class="navbar-logo" viewBox="0 0 32 32" fill="currentColor">
    <path d="M16 2 L30 9 L30 23 L16 30 L2 23 L2 9 Z" />
  </svg>
{% endblock %}

Overriding Field Templates

Each field context utilizes three sub-directories:

You can override the cell used for text fields without affecting the form or the detail display:

my_templates/
└── fields/
    └── list/
        └── text.html

To point a specific field instance to your custom template instead of overriding the type globally, set list_template, detail_template, form_template, null_template, or empty_template directly on the field definition:

from starlette_admin.fields import StringField

StringField("status", list_template="fields/list/status_badge.html")

null_template (default "fields/detail/_null.html") and empty_template (default "fields/detail/_empty.html") are separate slots rendered on the list and detail pages in place of list_template or detail_template, whenever the field's value is None or an empty list/tuple respectively:

StringField("status", null_template="fields/detail/_status_null.html")

Overriding Widget Templates

You can apply the exact same override pattern for widgets by placing files under the widgets/ directory:

my_templates/
└── widgets/
    └── stat_widget.html

Global Template Variables

These variables are available in every template without being passed explicitly. The Admin class installs them as Jinja2 globals once during setup:

Per-Page Context Variables

Beyond the global variables above, each page passes its own context dictionary to TemplateResponse.

list.html

detail.html

create.html / edit.html

Adding Your Own Globals and Filters

You can inject custom variables and functions into your templates by subclassing Admin and overriding __init__. Be sure to call super().__init__() first so self.templates is set up before you add to it:

from sqlalchemy import create_engine
from starlette_admin.contrib.sqla import Admin


class MyAdmin(Admin):
    def __init__(self, *args, **kwargs) -> None:
        super().__init__(*args, **kwargs)
        self.templates.env.globals["site_name"] = "My App"
        self.templates.env.filters["currency"] = lambda v: f"${v:,.2f}"


engine = create_engine("sqlite:///admin.sqlite")
admin = MyAdmin(engine, title="My Admin")

Built-in Jinja2 Filters

These filters are registered automatically on every admin instance during _setup_templates:

What's Next

• Form Layout: Split the create/edit forms into titled, optionally collapsible groups, and override _form_group.html to customize their markup.
• Custom Themes: Restyle the admin interface without altering individual templates.
• Custom Fields: Pair a field's Python class with its own specific list_template or form_template.
• Extension Points: Review the full list of pluggable configuration surfaces beyond basic templates.