The Django Singleton Model: How to Manage Page Headers Without a CMS

I've always wondered how to handle those single-record things in a CMS-driven site. You know what I mean — the home page hero, the blog page header, the pricing section banner. They're not a list. There's no "add another." There's exactly one of them, and a non-technical client or even your future self needs to be able to edit them from an admin panel without touching code.

For the longest time I either hardcoded the content and lived with the guilt, or reached for something heavyweight like Wagtail. But neither felt right for a lean Django + React setup.

The actual answer turned out to be embarrassingly simple: the singleton model pattern.

The Problem

Django models are designed to store collections of things. But some things aren't collections — they're configuration. A home page header isn't a list of headers. It's the header. One row. Forever.

If you leave it as a normal model, three bad things can happen:

1. Someone adds a second row in the admin and breaks the frontend.
2. You delete the only row and the API 404s until someone notices.
3. You have to write HomePageHeader.objects.first() everywhere and pray row 1 never becomes row 5.

The singleton pattern closes all three gaps.

The Implementation

The core trick lives in the model's save() method: force pk=1 before every write.

class HomePageHeader(models.Model):
    AVAILABILITY_CHOICES = [
        ("open_to_work", "Open to Work"),
        ("currently_booked", "Currently Booked"),
        ("freelance_only", "Freelance Only"),
    ]

    availability_status = models.CharField(
        max_length=20,
        choices=AVAILABILITY_CHOICES,
        default="open_to_work",
    )
    hero_image = models.ImageField(upload_to="hero/", blank=True, null=True)
    heading_line1 = models.CharField(max_length=100, default="BUILDING")
    heading_highlight = models.CharField(max_length=100, default="DIGITAL")
    heading_line2 = models.CharField(max_length=200, default="PRODUCTS THAT")
    heading_accent = models.CharField(max_length=100, default="SLAP.")
    subtitle = models.TextField(
        default="I'm Vicente Reyes. Freelance Full-Stack Developer, Shopify & WordPress Expert, & Musician.",
    )
    primary_button_label = models.CharField(max_length=100, default="View Projects")
    primary_button_url = models.CharField(max_length=200, default="#projects")
    secondary_button_label = models.CharField(max_length=100, default="Book a Call")
    secondary_button_url = models.URLField(
        default="https://calendly.com/vicentereyes/30min",
    )

    class Meta:
        verbose_name = "Home Page Header"
        verbose_name_plural = "Home Page Header"

    def __str__(self):
        return "Home Page Header"

    def save(self, *args, **kwargs):
        self.pk = 1
        super().save(*args, **kwargs)

That's the whole trick. By pinning self.pk = 1 before calling super().save(), Django will always INSERT OR REPLACE (or UPDATE) the same row. A second save never creates a second record — it just updates the first one.

The verbose_name_plural matching verbose_name is a small cosmetic touch: Django's admin sidebar normally pluralizes the label, so "Home Page Headers" would appear. Keeping both the same gives you "Home Page Header" in the sidebar — which correctly implies there's only one.

Locking Down the Admin

The model alone prevents duplicates at the database level, but the admin still shows an "Add" button. Lock it out explicitly:

@admin.register(HomePageHeader)
class HomePageHeaderAdmin(admin.ModelAdmin):
    list_display = ("availability_status", "heading_line1", "heading_highlight")

    def has_add_permission(self, request):
        return not HomePageHeader.objects.exists()

    def has_delete_permission(self, request, obj=None):
        return False

has_add_permission returns True only when the table is empty — meaning the first time the row is created, the "Add" button appears. Once it exists, the button disappears. has_delete_permission always returns False, making the row permanent from the admin's perspective.

The same pattern applies to every page header in the project:

@admin.register(BlogPageHeader)
class BlogPageHeaderAdmin(admin.ModelAdmin):
    list_display = ("badge_text", "heading_line1", "heading_highlight")

    def has_add_permission(self, request):
        return not BlogPageHeader.objects.exists()

    def has_delete_permission(self, request, obj=None):
        return False


@admin.register(ServicesPageHeader)
class ServicesPageHeaderAdmin(admin.ModelAdmin):
    list_display = ("heading", "subheading", "cta_heading")

    def has_add_permission(self, request):
        return not ServicesPageHeader.objects.exists()

    def has_delete_permission(self, request, obj=None):
        return False

Each page section gets its own model, its own admin class, and its own locked-down row.

The View

With the model and admin locked down, the view is a one-liner:

class HomePageHeaderView(APIView):
    def get(self, request):
        obj, _ = HomePageHeader.objects.get_or_create(pk=1)
        return Response(
            HomePageHeaderSerializer(obj, context={"request": request}).data,
        )

get_or_create(pk=1) is the runtime complement to the model-level pk=1 pin. If the row doesn't exist yet (fresh database, new environment), it creates one with all the field defaults. If it does exist, it returns it. The view never returns a 404 for a missing singleton — it self-heals.

The Serializer

Nothing special here, but the HomePageHeader has one field worth noting — availability_status uses Django choices, and the serializer surfaces both the raw value and the human-readable label:

class HomePageHeaderSerializer(serializers.ModelSerializer):
    availability_display = serializers.CharField(
        source="get_availability_status_display",
        read_only=True,
    )
    hero_image_url = serializers.SerializerMethodField()

    class Meta:
        model = HomePageHeader
        fields = [
            "availability_status",
            "availability_display",
            "hero_image_url",
            "heading_line1",
            "heading_highlight",
            "heading_line2",
            "heading_accent",
            "subtitle",
            "primary_button_label",
            "primary_button_url",
            "secondary_button_label",
            "secondary_button_url",
        ]

    def get_hero_image_url(self, obj):
        if not obj.hero_image:
            return None
        request = self.context.get("request")
        if request:
            return request.build_absolute_uri(obj.hero_image.url)
        return obj.hero_image.url

get_availability_status_display is a Django built-in that returns the human-readable choice label — so the frontend gets "Open to Work" rather than "open_to_work". The hero_image_url method builds an absolute URL so the React frontend gets a fully qualified image path regardless of where the API is hosted.

The Full Flow

The full stack for any singleton page header looks like this:

1. Model — fields with sensible defaults, save() pins pk=1
2. Migration — standard makemigrations / migrate
3. Admin — has_add_permission blocks duplicates, has_delete_permission blocks deletion
4. View — get_or_create(pk=1) for self-healing on fresh environments
5. Serializer — flat output, no nesting needed
6. Router — one URL, no {id} segment needed

The React side just does GET /api/home-header/ and maps the flat JSON to component props. No special handling, no conditional rendering for missing data.

When to Use This (and When Not To)

This pattern is ideal when:

• The content is truly a one-of-a-kind configuration for a specific page or section
• You want non-technical users to edit it from Django Admin
• You don't want to pull in a full CMS dependency

Skip it when:

• The content might ever need more than one instance (use a regular model)
• You have dozens of these (consider django-solo, which packages this pattern as a reusable base class and adds caching)
• The content changes rarely and has no images (environment variables or a settings dict is simpler)

Takeaway

The singleton model isn't exotic — it's just a model with one enforced row. Three lines of code in save() and two overrides in ModelAdmin are all it takes to turn a generic Django model into a safely editable, self-healing, single-record configuration object.

I spent way too long hardcoding hero text before I figured this out. Now every page section that needs admin-editable content but only ever has one instance gets this treatment by default.