Configuration Reference

This page provides a complete reference for all configuration options available in litestar-admin.

AdminConfig

The AdminConfig dataclass is the primary way to configure your admin panel. Pass it to the AdminPlugin when initializing your application.

from litestar_admin import AdminPlugin, AdminConfig

plugin = AdminPlugin(
    config=AdminConfig(
        title="My Admin",
        base_url="/admin",
        # ... more options
    )
)

Basic Settings

title

  • Type: str

  • Default: "Admin"

The title displayed in the admin panel header and browser tab.

AdminConfig(title="My Application Admin")

base_url

  • Type: str

  • Default: "/admin"

The base URL path for the admin panel. All admin routes will be prefixed with this path.

# Admin available at /dashboard
AdminConfig(base_url="/dashboard")

# Admin available at /app/admin
AdminConfig(base_url="/app/admin")

Note

The base_url must start with / and should not end with / (except when set to just /).

logo_url

  • Type: str | None

  • Default: None

URL for a custom logo image displayed in the sidebar header.

AdminConfig(logo_url="/static/images/logo.png")

favicon_url

  • Type: str | None

  • Default: None

URL for a custom favicon.

AdminConfig(favicon_url="/static/favicon.ico")

theme

  • Type: Literal["dark", "light"]

  • Default: "dark"

The color theme for the admin panel.

# Dark theme (default, Cloudflare-inspired)
AdminConfig(theme="dark")

# Light theme
AdminConfig(theme="light")

Authentication

auth_backend

  • Type: AuthBackend | None

  • Default: None

The authentication backend for securing the admin panel. When None, the admin panel is publicly accessible.

from litestar_admin.auth import JWTAuthBackend, JWTConfig

backend = JWTAuthBackend(
    config=JWTConfig(secret_key="your-secret-key"),
    user_loader=load_user_from_db,
)

AdminConfig(auth_backend=backend)

See Authentication for detailed authentication setup.

Model Discovery and Views

auto_discover

  • Type: bool

  • Default: True

Auto-discovery is on by default. The plugin finds your DeclarativeBase subclasses, walks their model registries, and generates views for any model that doesn’t already have an explicit ModelView. Generated views include all columns, make string columns searchable, and exclude auto-increment PKs from forms.

# This is enough — all your models get admin views
AdminConfig(title="My Admin")

# Turn it off if you only want explicitly registered views
AdminConfig(auto_discover=False, views=[UserAdmin, PostAdmin])

views

  • Type: list[type[BaseAdminView]]

  • Default: []

Explicit view classes to register. Use this when you need to customize column lists, permissions, form behavior, or lifecycle hooks for specific models. Auto-discovery skips any model that already has a view registered here.

from litestar_admin import AdminConfig, ModelView

class UserAdmin(ModelView, model=User):
    column_list = ["id", "email"]
    can_delete = False

# UserAdmin is explicit; other models still auto-discovered
AdminConfig(views=[UserAdmin])

Development

debug

  • Type: bool

  • Default: False

Enable debug mode for additional logging and error details.

AdminConfig(debug=True)

Warning

Do not enable debug mode in production as it may expose sensitive information.

Rate Limiting

rate_limit_enabled

  • Type: bool

  • Default: True

Whether to enable rate limiting on admin API endpoints.

# Disable rate limiting (not recommended for production)
AdminConfig(rate_limit_enabled=False)

rate_limit_requests

  • Type: int

  • Default: 100

Maximum number of requests allowed per window.

AdminConfig(rate_limit_requests=200)

rate_limit_window_seconds

  • Type: int

  • Default: 60

Rate limit window duration in seconds.

# 50 requests per 30 seconds
AdminConfig(
    rate_limit_requests=50,
    rate_limit_window_seconds=30,
)

Static Files

static_path

  • Type: str | None

  • Default: None

Path to a custom static files directory. When None, uses the built-in frontend.

# Use custom frontend build
AdminConfig(static_path="/path/to/custom/frontend/dist")

UI Customization

index_title

  • Type: str

  • Default: "Dashboard"

Title for the dashboard/index page.

AdminConfig(index_title="Overview")

Session Settings

Extra Settings

extra

  • Type: dict[str, Any]

  • Default: {}

Additional custom settings for extensibility.

AdminConfig(
    extra={
        "custom_setting": "value",
        "feature_flag": True,
    }
)

Complete Example

Here’s a comprehensive configuration example:

from litestar_admin import AdminPlugin, AdminConfig, ModelView
from litestar_admin.auth import JWTAuthBackend, JWTConfig

# Define your model views
class UserAdmin(ModelView, model=User):
    column_list = ["id", "email", "name", "is_active"]
    column_searchable_list = ["email", "name"]

class PostAdmin(ModelView, model=Post):
    column_list = ["id", "title", "published"]

# Create auth backend
async def load_user(user_id: str | int):
    # Load user from database
    ...

auth_backend = JWTAuthBackend(
    config=JWTConfig(
        secret_key="your-secure-secret-key",
        token_expiry=3600,
    ),
    user_loader=load_user,
)

# Configure admin
config = AdminConfig(
    # Basic settings
    title="My Application Admin",
    base_url="/admin",
    logo_url="/static/logo.png",
    theme="dark",

    # Authentication
    auth_backend=auth_backend,

    # Model views
    views=[UserAdmin, PostAdmin],
    auto_discover=True,

    # Rate limiting
    rate_limit_enabled=True,
    rate_limit_requests=100,
    rate_limit_window_seconds=60,

    # Session security
    session_cookie_secure=True,
    session_cookie_httponly=True,
    session_cookie_samesite="lax",

    # UI customization
    index_title="Dashboard",
)

# Create plugin
plugin = AdminPlugin(config=config)

Environment Variables

You can load configuration from environment variables:

import os

AdminConfig(
    title=os.getenv("ADMIN_TITLE", "Admin"),
    debug=os.getenv("DEBUG", "false").lower() == "true",
    rate_limit_requests=int(os.getenv("RATE_LIMIT_REQUESTS", "100")),
)

Computed Properties

AdminConfig provides several computed properties:

api_base_url

Returns the full API base URL (e.g., /admin/api).

config = AdminConfig(base_url="/admin")
print(config.api_base_url)  # "/admin/api"

static_base_url

Returns the full static files base URL (e.g., /admin/static).

config = AdminConfig(base_url="/admin")
print(config.static_base_url)  # "/admin/static"

Validation

AdminConfig validates settings on initialization:

# This will raise ValueError
AdminConfig(base_url="admin")  # Must start with /

# This will raise ValueError
AdminConfig(rate_limit_requests=0)  # Must be at least 1