Skip to content

Views

A ModelView[T] subclass configures one SQLAlchemy model. Register it with @admin.register; configuration errors (unknown column names, unsortable default sort, unfilterable filters, unknown export formats) raise at registration.

@admin.register
class TaskView(ModelView[Task]):
    model = Task
    name = "Task"  # default: the model class name
    name_plural = "Tasks"  # default: name + "s", so set it for "Category" -> "Categories"
    identity = "task"  # URL segment; default: model name, lower-case
    category = "Work"  # sidebar group
    icon = "table"  # any Lucide icon name; unknown names raise ValueError at registration

Options

Attribute Default Meaning
list_columns all columns Columns and relations shown in the list
detail_columns all columns and relations Fields on the detail page
searchable () Columns searched by ?q= (case-insensitive substring)
sortable every column in list_columns Columns with sortable headers
default_sort None ("column", "asc" \| "desc")
page_size / page_size_options 25 / (25, 50, 100) Pagination
list_filters () Filter panel; see Lists and filters
form_fields / form_exclude derived / () See Forms
export_formats / export_columns / export_max_rows () / list columns / 10_000 See Export
can_view / can_create / can_edit / can_delete True Enable pages and buttons

Badges

Every enum column renders as a badge, in lists, on the detail page and in the detail header; badges declares which tone each value gets. Undeclared enum values fall back to a neutral badge. Bool columns render as a check or cross icon unless declared here, in which case they become "Yes" / "No" badges.

class TaskView(ModelView[Task]):
    model = Task
    badges = {
        "status": {"done": "success", "doing": "accent", "todo": "neutral"},
        "archived": {"true": "neutral"},
    }

Keys are column names; inner keys are the enum's .value strings, or "true" / "false" for a bool column. Tones are "neutral" | "accent" | "success" | "warning" | "danger". An unknown column name, a value the column cannot hold (such as "Done" for "done") or an unknown tone raises ValueError at registration.

Detail page

The detail page at /{prefix}/{identity}/{pk} shows a back link to the list, the row's display as the title with up to two enum badges, and the actions on the right: the row actions as buttons when there are at most two and none needs confirmation (otherwise they move into the ⋯ menu), Edit, and a ⋯ menu holding Delete. The body is a card holding a description list, two columns wide from the md breakpoint with each label above its value: the columns first, then the to-one relations in their own group. Long text and JSON span both columns. Values use the same cell formatting as the list; relations link to the related row when its model has a view with can_view that the current user can access. When detail_columns is empty, foreign-key columns whose relation is also shown are hidden. To-many relations appear as tabs below, each loading its list when first shown, through the related view's get_query. A relation whose view is not accessible to the current user gets no tab; one whose model has no view shows up to 100 rows as plain text.

Hooks

Method Purpose
get_query(request) Base select() for every list, detail, action and export; scope rows here
format_<column>(obj) Display override for one column, used in lists, detail and export
display(obj) Label of a row (default: str(obj) if the model defines __str__, otherwise the name and primary key, like Task 3)
on_save(request, session, obj, *, created) Runs before commit on create and edit; see Forms
on_delete(request, session, obj) Runs before delete
is_visible(request) Show the view in the sidebar, dashboard and command palette
is_accessible(request) Allow access at all (403 otherwise); an inaccessible view is also left out of the sidebar, dashboard and palette
is_action_allowed(request, name) Allow one action; see Actions

request.state.hxadmin_user is whatever your auth dependency returned, so the hooks can decide per user. The examples below assume the auth from Auth and sessions, which returns the signed-in User row.

Scoping rows with get_query

from sqlalchemy import Select
from starlette.requests import Request


@admin.register
class TaskView(ModelView[Task]):
    model = Task

    def get_query(self, request: Request) -> Select[Task]:
        stmt = super().get_query(request).where(Task.archived.is_(False))
        user = request.state.hxadmin_user
        if not user.is_superuser:
            stmt = stmt.where(Task.assignee_id == user.id)
        return stmt

Everything that reads rows goes through get_query: the list and its count, the detail page, edit and delete, row and bulk actions, export, the dashboard count, the command palette, and the relation comboboxes and filters of other views that point at Task. A row outside the query answers 404, so a user cannot reach it by guessing its URL either.

get_query scopes reads, not writes: a non-superuser can still create a task assigned to someone else, after which it disappears from their list. Guard that in on_save with a FormError if it matters.

Keep get_query a plain select(...) of the model, narrowed with where (and options or join as needed). hxadmin adds its own search, filters, order and pagination on top. An order_by in it orders the list while no column is sorted (with the primary key as tie-breaker); sorting a column, or a default_sort, replaces it.

Formatting a column

class TaskView(ModelView[Task]):
    model = Task

    def format_due_date(self, obj: Task) -> str:
        return obj.due_date.strftime("%d %b %Y") if obj.due_date else "No due date"

The returned value is shown as text (HTML-escaped) in the list, the detail page and exports, in place of hxadmin's own rendering. A formatted enum or bool column therefore loses its badge or icon, and a formatted relation its link, so prefer badges for those. Exports get the formatted text too, so a formatted date column exports as text rather than as a date cell.

Access per view

@admin.register
class UserView(ModelView[User]):
    model = User

    def is_accessible(self, request: Request) -> bool:
        return request.state.hxadmin_user.is_superuser

is_accessible is enforced: every route of the view answers 403 for other users, and relations pointing at User from other views are locked (see Lists and filters and Forms): detail pages show them as plain text instead of links and leave out their tabs. is_visible only hides the view from the sidebar, dashboard and palette; its URLs keep working. Use is_visible for views that are reachable through links but too noisy for the sidebar, and is_accessible for anything that is a permission.

Async and relations

Relationships used in lists and detail are eager-loaded. Anything a template or format_ method touches beyond those must be loaded by get_query, because async SQLAlchemy cannot lazy-load: touching an unloaded relationship raises MissingGreenlet. For example, to show the project's name next to the title in a list that does not have a project column:

from sqlalchemy.orm import selectinload


class TaskView(ModelView[Task]):
    model = Task
    list_columns = ("title", "status")

    def get_query(self, request: Request) -> Select[Task]:
        return super().get_query(request).options(selectinload(Task.project))

    def format_title(self, obj: Task) -> str:
        return f"{obj.title} ({obj.project.name})"

format_ and display are plain synchronous methods, so they cannot run queries themselves.

Helpers

A registered view also has methods and attributes that hxadmin's templates use. They are useful in template overrides and custom pages; admin.view_for(Model) returns the view registered for a model, or None.

Method Returns
pk_of(obj) The row's primary key as it appears in URLs (composite keys ;-joined)
pk_clauses(pk) where clauses matching a URL primary key, for select(...).where(*view.pk_clauses(pk))
cell(obj, name) The value shown for a field: format_<name>(obj) when defined, else the attribute
badge_tone(name, raw) The badges tone of one value ("neutral" when none is declared)
permitted_actions(request, *, bulk) The row or bulk actions the current user may run, in declaration order; each has name, label, bulk, confirm and method
action_handler(name) The bound handler method of an action

These attributes are resolved once at registration and should be treated as read-only:

Attribute Holds
fields Every column and relationship of the model, by name
pk_names Names of the primary key columns
list_fields, detail_fields, export_fields The fields of the list, detail page and export, in order
writable_fields, edit_fields The fields of the create form, and of the edit form (without primary keys)
link_name, stretch_name The list's primary column (see Table) and the column that takes the remaining width, or None
sort_names The columns the list can sort by
formatted Names of the fields with a format_<name> method
filters The list's filters, in list_filters order
actions, row_actions, bulk_actions Declared actions: all of them by name, then the row and bulk ones in declaration order
create_schema, edit_schema The pydantic models validating the create and edit forms