How to Use Fieldsets in Django Admin for Better Form Layout

In Django admin, use the fieldsets attribute inside your ModelAdmin class to group model fields into sections with optional titles and descriptions. Each fieldset is a tuple with a title and a dictionary specifying which fields to include and optional CSS classes. This helps organize the admin form for better clarity and usability.

Syntax

The fieldsets attribute is a tuple of tuples. Each inner tuple defines a section in the admin form. It has two parts:

• Title: A string shown as the section header.
• Options dictionary: Contains keys like fields (list of field names to show) and optional classes for styling.

This structure lets you group fields logically in the admin interface.

python

class MyModelAdmin(admin.ModelAdmin):
    fieldsets = (
        ('Section Title', {
            'fields': ('field1', 'field2'),
            'classes': ('collapse',),  # optional
        }),
        ('Another Section', {
            'fields': ('field3',),
        }),
    )

Example

This example shows how to organize a Book model's admin form into two sections: "Basic Info" and "Details". The "Details" section is collapsible for cleaner UI.

python

from django.contrib import admin
from .models import Book

class BookAdmin(admin.ModelAdmin):
    fieldsets = (
        ('Basic Info', {
            'fields': ('title', 'author')
        }),
        ('Details', {
            'fields': ('summary', 'isbn'),
            'classes': ('collapse',),
        }),
    )

admin.site.register(Book, BookAdmin)

Output

In the Django admin, the Book form will show two sections: "Basic Info" with title and author fields always visible, and "Details" with summary and isbn fields inside a collapsible panel.

Common Pitfalls

Common mistakes when using fieldsets include:

• Not including all required fields in any fieldset, causing validation errors.
• Using field names that don't exist on the model.
• Forgetting to use tuples for fieldsets and instead using lists or other types.
• Misusing the classes option without understanding its effect (e.g., collapse makes the section collapsible).

Always ensure every field you want editable is inside some fieldset.

python

class WrongAdmin(admin.ModelAdmin):
    fieldsets = [  # should be tuple, not list
        ('Main', {
            'fields': ('nonexistent_field',),  # wrong field name
        }),
    ]

class CorrectAdmin(admin.ModelAdmin):
    fieldsets = (
        ('Main', {
            'fields': ('existing_field',),
        }),
    )

Quick Reference

• fieldsets: tuple of (title, options dict) tuples.
• fields: list or tuple of field names to show in that section.
• classes: optional tuple of CSS classes like collapse to style the section.
• Use fieldsets to group related fields and improve admin form clarity.

Key Takeaways

Use the fieldsets attribute in ModelAdmin to group fields into titled sections.

Each fieldset is a tuple with a title and a dictionary specifying fields and optional classes.

Include all editable fields inside fieldsets to avoid validation errors.

Use the 'collapse' class to make sections collapsible for cleaner admin UI.

Field names in fieldsets must exactly match model field names.