Field Types Overview

Django Admin provides specialized field types that automatically handle formatting, display, and rendering. This guide helps you choose the right field type for your data.

Quick Reference

Field Type	Purpose	Use Case	Documentation
BadgeField	Colored badges with icons	Status, categories, tags	→ Basic Fields
BooleanField	Boolean indicators	Active/inactive, flags	→ Basic Fields
TextField	Text with truncation	Descriptions, content	→ Basic Fields
AvatarField	User avatars with fallback	Profile pictures, user identity	→ Display Fields
UserField	User display with avatar	Authors, assignees	→ Display Fields
LinkField	Text with external link	Usernames, external resources	→ Display Fields
ImageField	Images with captions	QR codes, photos	→ Display Fields
ImagePreviewField	Image preview with modal	Photos, thumbnails	→ Display Fields
VideoField	Video thumbnail with platform detection	YouTube, Vimeo	→ Display Fields
CurrencyField	Formatted currency	Prices, totals, balances	→ Formatting Fields
DateTimeField	Formatted dates/times	Created, updated, published	→ Formatting Fields
ShortUUIDField	Shortened UUIDs	Primary keys, identifiers	→ Formatting Fields
StatusBadgesField	Multiple conditional badges	User flags, permissions	→ Advanced Fields
CounterBadgeField	Counter badge with link	Message counts, view counts	→ Advanced Fields
MarkdownField	Markdown content rendering	Documentation, rich text	→ Advanced Fields

Choosing the Right Field

For Status/Categories


# Single status with colors
BadgeField(name="status", label_map={"active": "success", "inactive": "secondary"})
 
# Multiple status flags
StatusBadgesField(
    name="user_flags",
    badge_rules=[
        BadgeRule(condition_field="is_verified", label="Verified", variant="success"),
        BadgeRule(condition_field="is_premium", label="Premium", variant="warning"),
    ]
)

For User Display


# Avatar with initials fallback
AvatarField(
    name="first_name",
    photo_field="photo_file",
    name_field="display_name",
    initials_field="first_name"
)
 
# Simple user display
UserField(name="author", header=True)

For Numbers


# Money
CurrencyField(name="price", currency="USD", precision=2)
 
# Counts with links
CounterBadgeField(
    name="messages_badge",
    count_field="messages_count",
    link_url_template="/admin/app/message/?user__id={obj.id}"
)

For Dates


# Relative time ("2 hours ago")
DateTimeField(name="created_at", show_relative=True)
 
# Custom format
DateTimeField(name="published_at", format="%B %d, %Y")

Common Patterns

E-commerce Admin


from django_cfg.modules.django_admin import (
    AdminConfig,
    AvatarField,
    BadgeField,
    CurrencyField,
    DateTimeField,
)
 
config = AdminConfig(
    model=Order,
    display_fields=[
        AvatarField(name="user", ...),  # Customer avatar
        CurrencyField(name="total", currency="USD"),  # Order total
        BadgeField(name="status", label_map={...}),  # Order status
        DateTimeField(name="created_at", show_relative=True),  # When ordered
    ]
)

User Management Admin


display_fields=[
    AvatarField(name="first_name", ...),  # User avatar
    StatusBadgesField(name="flags", badge_rules=[...]),  # User flags
    CounterBadgeField(name="posts", count_field="post_count"),  # Post count
    DateTimeField(name="last_login", show_relative=True),  # Last seen
]

Content Management Admin


display_fields=[
    ImagePreviewField(name="thumbnail", thumbnail_max_width=100),  # Clickable thumbnail with modal
    LinkField(name="title", link_field="url"),  # Article title with link
    BadgeField(name="status", ...),  # Publication status
    UserField(name="author", header=True),  # Article author
]

Important Notes

Field Name Must Be Real The name parameter in field configs MUST be a real model field, not a virtual field or @property.

❌ Wrong:


AvatarField(name="user_avatar", ...)  # Virtual field

✅ Correct:


AvatarField(name="first_name", ...)  # Real CharField

Use select_related For fields that reference related models (UserField, AvatarField with ForeignKey), always use select_related to avoid N+1 queries:


config = AdminConfig(
    model=Order,
    select_related=["user", "product"],  # Important!
    display_fields=[
        UserField(name="user", ...),
    ]
)

Next Steps

Basic Fields - BadgeField, BooleanField, TextField
Display Fields - AvatarField, UserField, LinkField, ImageField
Formatting Fields - CurrencyField, DateTimeField, ShortUUIDField
Advanced Fields - StatusBadgesField, CounterBadgeField, MarkdownField
Examples - Real-world usage examples
API Reference - Complete API documentation

Field Types Overview

Quick Reference

Categories

Basic Fields

Display Fields

Formatting Fields

Advanced Fields