ModelAdmin

ModelAdmin is the configuration class for each registered model. It controls changelist columns, filters, forms, permissions, and lifecycle hooks.

Basic configuration

class ProductAdmin(ModelAdmin):
    model = Product                    # Pydantic model
    collection_name = "products"       # MongoDB collection (required)
    list_display = ["name", "price", "active"]
    list_display_links = ["name"]
    list_filter = ["category", "active"]
    search_fields = ["name", "category"]
    list_per_page = 25
    ordering = ["-created_at"]

Configuration reference

Option	Description
model	Pydantic BaseModel for validation and form inference
collection_name	MongoDB collection name (required)
list_display	Changelist columns — field names or @display methods
list_display_links	Clickable columns (default: first column)
list_editable	Fields editable inline on the changelist
list_filter	Field names or ListFilter subclasses
search_fields	Fields searched with case-insensitive regex
list_per_page	Pagination size (default: 25)
list_max_show_all	Max rows when “show all” is selected (default: 200)
ordering	Default sort; prefix with - for descending
date_hierarchy	Field name for year/month/day drill-down navigation
list_select_related	{"field": "collection"} for related document lookups
fieldsets	Grouped change form layout
readonly_fields	Non-editable fields on change forms
field_mapping	Model field → MongoDB key mapping
actions	Enabled bulk action method names
choices	Choice lookups for filters and select widgets
formfield_overrides	Per-field widget and HTML attribute overrides
date_format	Display format for date fields (default: 8 Apr 2026)
datetime_format	Display format for datetime fields (default: 8 Apr 2026, 7:32pm)

Template overrides

Attribute	Default template
change_list_template	admin/change_list.html
change_form_template	admin/change_form.html
delete_confirmation_template	admin/delete_confirmation.html

Display columns

Field names

Reference model fields directly in list_display:

list_display = ["name", "price", "active"]

@display decorator

Add computed columns with custom rendering:

from fastapi_mongo_admin import display


@display(description="Price", ordering="price")
def price_display(self, obj: dict) -> str:
    return f"${obj.get('price', 0):,.2f}"

The ordering parameter enables sortable columns (maps to the underlying field).

Fieldsets

Group fields on add/change forms:

fieldsets = [
    ("Basic info", {"fields": ["name", "sku", "description"]}),
    ("Pricing", {"fields": ["price", "compare_at_price", "is_taxable"]}),
    ("Timestamps", {"fields": ["created_at", "updated_at"]}),
]

If fieldsets is not set, all model fields appear in a single group.

Readonly fields

readonly_fields = ["created_at", "updated_at", "order_number"]

Readonly fields are displayed but not submitted on update. Existing values are preserved when the field is absent from the form POST.

Choices

Provide discrete values for filters and select form widgets:

choices = {
    "status": [
        ("draft", "Draft"),
        ("published", "Published"),
        ("archived", "Archived"),
    ],
}

Enum fields can be generated dynamically:

choices = {
    "status": [(s.value, s.name.replace("_", " ").title()) for s in ProductStatus],
}

Date hierarchy

Enable year → month → day drill-down on a date/datetime field:

date_hierarchy = "published_at"

Navigation links appear above the changelist. Query params year, month, and day filter results progressively.

List select related

Resolve ObjectId references to related documents for display:

list_select_related = {
    "category_id": "categories",
    "brand_id": "brands",
}

On the changelist, related documents are fetched and a human-readable label is shown instead of the raw id. On add/change forms, the same configuration renders those fields as searchable dropdowns. Options are fetched from the related collection only after the user types at least two characters. Explicit choices on ModelAdmin take precedence over searchable related widgets.

Date and time display

date and datetime fields are auto-formatted on changelists and readonly form fields. See Date, Time, and Save Messages for defaults and customization.

Object representation

object_repr(request, obj) returns a human-readable label for an object. It is used for:

• Save success messages ("Widget Pro" was saved successfully.)

• Bulk delete confirmation rows

Override to customize the label shown in flash messages.

Configurable methods

Override these methods for dynamic behavior:

Method	Purpose
get_list_display(request)	Dynamic changelist columns
get_list_display_links(request)	Dynamic link columns
get_search_fields()	Dynamic search fields
get_ordering()	Dynamic default ordering
get_readonly_fields(request, obj)	Context-dependent readonly fields
get_fieldsets(request, obj)	Dynamic form layout
get_list_filters(request, params)	Custom filter instantiation
get_actions()	Control which bulk actions are available
get_queryset(request, base_query)	Add base MongoDB filter to all queries
get_formfield_overrides(request, obj)	Dynamic widget overrides
formfield_for_field(field, request, obj)	Per-field customization hook
format_date_value(value)	Custom date display formatting
format_datetime_value(value)	Custom datetime display formatting
object_repr(request, obj)	Human-readable label for flash messages
display_value(request, obj, field_name)	Resolve changelist cell values (includes date/datetime formatting)

See Lifecycle Hooks for lifecycle hooks (save_model, delete_model, etc.). See Date, Time, and Save Messages for date/time display and save notifications.

See API Reference for the full ModelAdmin API.