GitHubEmailContact
Skip to main content

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 TypePurposeUse CaseDocumentation
BadgeFieldColored badges with iconsStatus, categories, tags→ Basic Fields
BooleanFieldBoolean indicatorsActive/inactive, flags→ Basic Fields
TextFieldText with truncationDescriptions, content→ Basic Fields
AvatarFieldUser avatars with fallbackProfile pictures, user identity→ Display Fields
UserFieldUser display with avatarAuthors, assignees→ Display Fields
LinkFieldText with external linkUsernames, external resources→ Display Fields
ImageFieldImages with captionsQR codes, photos→ Display Fields
ImagePreviewFieldImage preview with modalPhotos, thumbnails→ Display Fields
VideoFieldVideo thumbnail with platform detectionYouTube, Vimeo→ Display Fields
CurrencyFieldFormatted currencyPrices, totals, balances→ Formatting Fields
DateTimeFieldFormatted dates/timesCreated, updated, published→ Formatting Fields
ShortUUIDFieldShortened UUIDsPrimary keys, identifiers→ Formatting Fields
StatusBadgesFieldMultiple conditional badgesUser flags, permissions→ Advanced Fields
CounterBadgeFieldCounter badge with linkMessage counts, view counts→ Advanced Fields
MarkdownFieldMarkdown content renderingDocumentation, rich text→ Advanced Fields

Categories​

Basic Fields​

Simple fields for common data types: badges, booleans, and text.

→ See Basic Fields Documentation

  • BadgeField - Display values as colored badges
  • BooleanField - Boolean indicators with icons
  • TextField - Text with optional truncation

Display Fields​

Rich display fields for complex UI elements: avatars, users, links, and images.

→ See Display Fields Documentation

  • AvatarField - User avatars with initials fallback
  • UserField - User display with avatar
  • LinkField - Text with clickable link
  • ImageField - Images with captions
  • ImagePreviewField - Image preview with modal zoom/pan
  • VideoField - Video thumbnails (YouTube, Vimeo, direct)

Formatting Fields​

Fields that format numbers, dates, and identifiers.

→ See Formatting Fields Documentation

  • CurrencyField - Formatted currency amounts
  • DateTimeField - Formatted dates with relative time
  • ShortUUIDField - Shortened UUIDs with tooltip

Advanced Fields​

Complex fields with conditional logic and special behaviors.

→ See Advanced Fields Documentation

  • StatusBadgesField - Multiple conditional badges
  • CounterBadgeField - Counter badge with optional link
  • MarkdownField - Markdown content rendering

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​

Last updated on