How to Choose a Headless CMS: 10-Point Checklist (2026)

Most teams pick a headless CMS by reading the marketing page and trusting the demo. Six months later, they discover the data model doesn't fit, the pricing scales worse than expected, and the editor experience makes content people miserable. The checklist below is what we wish every team ran before signing.

This is a 10-point evaluation framework for choosing a headless CMS in 2026, with how to test each item, what red flags look like, and what "good" actually means in practice. TL;DR: walk all 10 items with the actual content team and the actual codebase. Run a 1-week trial — not a 30-minute demo — on the top 2 candidates. The deciding criteria are usually data model fit, editor UX, and pricing-at-scale; everything else is recoverable. See also: the full headless CMS reference for 2026.

The audience: technical buyers in the last week before signing a headless CMS contract. If you've already narrowed to 2-3 candidates, this checklist tells you which one wins. If you're still researching, what is a headless CMS and the best CMS for React developers in 2026 are better starting points.

How to Use This Checklist

The 10 items are weighted differently for different projects. Score each one as critical / important / nice-to-have for your specific case before evaluating, then test each candidate against the criteria. The scoring matters more than the raw count — a CMS that nails 8 items but fails your one critical item is the wrong pick.

Don't skip the "test it" instructions. CMS marketing pages all sound the same; the difference shows up in the 30-minute hands-on test. Allocate 4-6 hours per candidate for a real evaluation.

1. Data Model Fit: Does the Schema Match Your Actual Content?

What to evaluate: Whether the CMS can model your content shapes natively, without forcing them through workarounds.

Most headless CMS demos use a "blog post + author + category" schema because it's universal. Your actual content is messier — events with recurring schedules, products with variants, courses with prerequisites, members with subscription tiers, multi-author articles with translator credits. The question is whether the CMS handles your specific shapes, not the demo shapes.

How to test: Take your three most complex content types and try to model them in the candidate CMS. Not on paper — actually create the content types in the admin, add 5-10 sample records, and write a query that fetches them with all relations populated. Time how long this takes. If it takes more than 2 hours, the data-model fit is poor.

Red flags:

• "Reference fields" that limit you to one direction (you can link Post → Author but not query "all posts by Author X" without a separate query)
• No real one-to-many or many-to-many relations — only flat fields
• Custom types limited to 5-10 fields, or fields limited to a fixed type list with no escape hatch
• "Rich text" stored as a vendor-specific JSON AST you have to render with their library

What good looks like:

• Real database-level relations (foreign keys or document references) with bidirectional querying
• Custom field types you can extend or define
• Schema-as-code: your content model lives in a file you can version-control
• Migrations: schema changes track in git, not in admin UI clicks
• A query language (GraphQL, GROQ, or SQL via self-hosted) that can express the joins you need

For more on what good content modeling looks like architecturally, see what makes a CMS developer-friendly. For self-hosted options where the data model is just your database schema, see best self-hosted CMS platforms in 2026.

2. API Quality: REST, GraphQL, Both, or SDK?

What to evaluate: How content actually leaves the CMS and reaches your frontend — and how much code you'll write to make that work.

The API is your real integration surface. Marketing pages all say "REST and GraphQL" but the practical quality varies widely. Some CMSes have generated TypeScript types from your schema; some have hand-written types that lag behind reality. Some have draft-mode endpoints; some make you hit the same API with different auth and pray. Some have rate limits that bite at small traffic; some bill per request.

How to test: Write a real query against the CMS API for your most complex page. Fetch the data your component actually needs — including nested relations, image URLs, and localizations if relevant. Time the round-trip. Then write the same query during a draft preview. Then check whether you can run the same query from a server component (RSC) without auth gymnastics.

Red flags:

• REST with deeply-nested populates that hit timeout limits at modest content size
• GraphQL with no codegen story — types maintained by hand
• Different endpoints for "live" vs "draft" content with different auth
• Rate limits at the free or entry tiers that interfere with normal development (Contentful's free tier was historically aggressive about this)
• No way to fetch a single field — every query returns the full document

What good looks like:

• REST + GraphQL both available, with REST being a sensible default for simple fetches
• TypeScript types generated from schema (Sanity's sanity typegen, Strapi's strapi typegen, Hygraph's GraphQL codegen, Payload's inferred types)
• Draft preview that works without a separate auth flow
• Reasonable rate limits at every tier, with clear documentation of what counts as a "request"
• Field selection — fetch only the fields you need

For framework-specific API picks, see the best CMS for React developers in 2026, best CMS for Next.js, and the framework comparison pages.

3. Editor UX: Will the Content Team Actually Use It?

What to evaluate: Whether the people who edit content daily will be productive — or fighting the CMS.

Engineers pick CMSes; editors live in them. The technical decision-makers in the room often miss editor UX issues that turn into "the marketing team uses Google Docs and emails me to update the site" within 3 months of launch.

How to test: Actually test with the actual editor. Hand one of your editors a candidate CMS for 30 minutes. Have them try to: (a) create a new post with a featured image, (b) edit an existing page with a typo, (c) preview their edit before publishing, (d) revert a change. Watch what frustrates them. Their reaction is the deciding signal — engineers can adapt to almost any admin; editors won't.

Red flags:

• Form-shaped admins where editing is a list of fields without context (Strapi and Directus lean this way for content-heavy work)
• No live preview or preview that requires a second tool
• "Reference field" UX where adding an author means searching by ID instead of typing a name
• Image upload buried in a separate media library tab instead of inline in the post editor
• No spellcheck, no draft autosave, no comment threads on drafts
• Performance: 2+ second saves, slow page loads in the admin

What good looks like:

• The editor opens directly to the writing surface — minimal chrome, focus on content
• Inline image upload, drag-and-drop reordering, autosave drafts
• Live preview that shows the actual rendered page (not a dev preview behind auth)
• Reference fields with autocomplete by name, not ID
• Multi-user collaboration: see who else is editing, comment on drafts, role-based permissions
• Fast: under 500ms to save, under 1s to load any admin page

Ghost wins this category for publication-shaped content. Storyblok wins for visual-editing of marketing pages with non-technical editors. Sanity Studio is highly customizable but the default UX is engineer-friendly more than editor-friendly. For headless CMSes that lean engineering-shaped (Strapi, Directus, Payload), be honest with the editor team about what they're getting.

For more on the editor-UX comparison across CMSes, see the head-to-head pages: UnfoldCMS vs Sanity, vs Contentful, vs Storyblok, vs Strapi.

4. Preview and Draft Workflow: Can Editors See Their Work Before Publishing?

What to evaluate: Whether content can be staged, previewed in the actual rendered context, and shared with reviewers before going live.

Preview is the difference between editors who trust the CMS and editors who write everything in Google Docs first. A working preview means an editor can write a post, see it rendered exactly as it'll look on the site, share that preview URL with a reviewer, get feedback, edit, and publish — all without involving an engineer.

How to test: Write a post in the candidate CMS, click preview, and see it render. Now share the preview URL with someone who isn't logged in. Does it work? If it requires re-auth or only works for the editor, the workflow is broken.

Red flags:

• Preview that only works in the admin's iframe, not as a standalone URL
• Preview that requires a separate environment variable or config change to enable
• Draft tokens that expire in 5 minutes, breaking review-by-Slack workflows
• Preview that shows different content than production (e.g., draft preview missing image transformations)
• No visual indication that a post has unpublished changes vs. matches what's live

What good looks like:

• Shareable preview URLs that work for unauthenticated reviewers (with token-based access)
• Preview renders the actual site, not a separate "preview mode" that diverges in styling
• Clear status indicators: draft, scheduled, published, has-pending-changes
• Schedule-publish: pick a future date and the post auto-publishes
• Optional draft autosave so a browser crash doesn't lose 3 hours of writing

For headless setups, draft-mode integration with Next.js (App Router), Astro, or SvelteKit matters specifically — see headless CMS and SEO: what actually matters in 2026 for the SEO implications of draft and preview, and the framework pages (Next.js, Astro, SvelteKit) for framework-specific preview patterns.

5. Localization: How Many Languages, How Many Headaches?

What to evaluate: Whether the CMS handles multi-language content as a first-class feature, or as an awkward bolt-on.

Localization (l10n) gets dismissed in early evaluation ("we'll add languages later") and bites teams six months later when they discover the CMS treats translations as separate documents instead of linked variants. If multi-language is anywhere on your roadmap, evaluate this now — switching CMSes to fix l10n is a major project.

How to test: Create the same content type in two languages with linked translation status. Try to: (a) see which fields are translated vs missing, (b) push a single source change to all locales without re-translating, (c) query your frontend with a locale parameter and get the right variant.

Red flags:

• Translations stored as duplicate documents with no link between them
• No "fallback to source language" when a locale is missing — you get nothing instead
• Locale support that requires the Enterprise tier (Contentful historically restricted locales by tier)
• API queries where locale is in the URL path, forcing your routing to be locale-aware everywhere
• No translation memory or workflow integration — every translation is a fresh paste from a translator

What good looks like:

• Locales as field-level variants, not document-level duplicates
• Visual indicator of translation completeness per field
• Single query that returns "best available locale" with documented fallback rules
• Locale parameter on every API call, defaulting to a primary locale
• Translation workflow integration (Lokalise, Crowdin, Phrase) if your team uses external translators

DatoCMS, Storyblok, and Contentful have strong native l10n stories. Sanity has it via plugins; you build the variant logic yourself. Strapi v5 improved l10n significantly but the pattern still feels added-on. For self-hosted, Statamic and UnfoldCMS handle l10n via Laravel's localization layer, which works but isn't the same as a CMS-first design.

6. Content Versioning and History: Can You Roll Back a Bad Edit?

What to evaluate: Whether the CMS keeps a version history of every edit, who made it, and lets you restore a previous version.

Sounds like a checkbox feature; isn't. The "marketing team accidentally republished a draft from 2023" scenario happens at every long-running site, and the difference between "click restore" and "diff the database backups" is a real operational distinction.

How to test: Edit a published post 5 times, save each version, then try to restore version 3. Check whether you can see who made each edit, when, and what changed.

Red flags:

• No version history at all — only the current state is kept
• Version history limited to the last 10 edits or last 30 days (most SaaS free tiers cap this)
• Restore that overwrites without confirmation or audit log
• No diff view — you see "version 3 from May 12" with no indication of what's different
• Author attribution missing or incorrect (everyone shows as "system" or "admin")

What good looks like:

• Unlimited version history (or enough that "last year's version" is recoverable)
• Visual diff of what changed between versions
• Author attribution per change with timestamp
• Roll back creates a new version (doesn't overwrite history)
• Audit log accessible to admins, not just the editor who made the change

Sanity, Contentful (paid tiers), and DatoCMS have strong version history. Strapi has it as a paid Enterprise feature. Self-hosted CMSes either have it natively (Statamic, Craft, UnfoldCMS via activity log) or don't (some smaller open-source projects). For regulated industries (healthcare, finance), version history is often a compliance requirement, not a nice-to-have — see self-hosted CMS and GDPR: data sovereignty in 2026 for the audit-trail angle.

7. Media Library and Image Transformations

What to evaluate: How the CMS stores, organizes, and transforms images — because this is 70-90% of the data volume of a real site.

Every CMS claims a "media library." The quality varies massively. Strong media handling has tag-based organization, on-the-fly image transformations (responsive sizes, WebP/AVIF conversion, focal-point cropping), and CDN delivery. Weak media handling is "upload a JPG, get a URL, fend for yourself."

How to test: Upload 20 images of varying sizes (5MB-15MB JPGs from a phone, plus a few PNGs and SVGs). Try to: (a) tag them and search by tag, (b) request a 800px-wide WebP version of a 12MB original, (c) crop with a focal point that follows on every transformation, (d) check the URL pattern — can you generate a transform URL programmatically?

Red flags:

• No automatic format conversion — you upload JPGs, you serve JPGs, even when WebP would be 30% smaller
• Image transformations require a separate service (Cloudinary, imgix) — they work but add cost and complexity
• No focal point or crop hints — responsive cropping shows random parts of the image
• Media library that's a flat list of every upload with no folders or tags
• No image-by-image alt-text field, or alt-text stored separately from the image

What good looks like:

• On-the-fly transformations via URL parameters: ?w=800&format=webp&fit=cover&fp-x=0.4&fp-y=0.6
• Auto-conversion to modern formats based on browser support
• Focal-point cropping per image
• Tags or folders for organization, search across them
• Alt-text and caption fields per image, returned in API responses
• CDN delivery with sensible cache headers

Sanity and DatoCMS have excellent image pipelines (DatoCMS in particular). Contentful is decent. Storyblok works. Strapi requires Cloudinary or similar for serious image work. Self-hosted CMSes vary — UnfoldCMS uses Spatie Media Library with image conversions, which works for common cases but isn't as polished as dedicated SaaS image services.

For sites where image volume is huge (e-commerce, portfolios, photo journalism), image-handling quality may be the deciding criterion — more important than data model fit or editor UX.

8. Pricing Model and Scaling Math

What to evaluate: What you'll pay at year 1, year 2, and year 3 — including the surprise costs that aren't on the pricing page.

SaaS CMS pricing has three knobs vendors turn: records, API requests, and users/seats. Self-hosted CMSes have one knob: hosting cost. The pricing page shows the entry tier; the deciding number is the year-3 bill at projected scale.

How to test: Project your year-3 numbers — content count, traffic, locales, editors — and run them through each candidate's pricing calculator. Then add 30% for surprise growth. Most teams discover the year-3 cost is 3-5x the year-1 cost. If that math breaks the budget, the CMS is wrong regardless of how good the product is.

Red flags:

• Per-record limits that force tier upgrades at predictable content milestones (Contentful's 25k → 50k record jump)
• Per-API-request billing where ISR or revalidation patterns drive cost (Sanity's CDN bandwidth tier)
• Per-user/seat pricing that punishes growth (Storyblok Business at $660/month limits seats)
• Locale tiers — paying extra to add languages
• "Enterprise" features (RBAC, SSO, audit logs, content history) gated behind a sales call
• Bandwidth or egress fees not on the public pricing page

What good looks like:

• Predictable pricing that scales with one or two clear axes (e.g., "$X per editor + $Y per million records")
• Clear tier limits with documented overage costs
• Generous free tier or self-hosted option for prototypes and small projects
• No surprise fees at scale — what you see on the pricing page is what you pay
• For self-hosted: just the VPS bill, no platform license tax

For the scaling math comparison, the 5 benefits of self-hosting beyond cost covers the predictability angle in detail. For specific platforms, the vs-Contentful and vs-Sanity head-to-heads break down pricing tiers.

9. Self-Host Option and Data Ownership

What to evaluate: Whether you can run the CMS on your own infrastructure, and what that buys you.

Self-hosting is a binary feature on most CMSes — either it's possible (Strapi, Directus, Payload, Statamic, Craft, UnfoldCMS) or it's not (Contentful, Sanity, Storyblok, Hygraph, DatoCMS). For some projects this is irrelevant; for regulated industries, GDPR-sensitive workloads, or teams burned by SaaS pricing changes, it's the deciding factor.

How to test: Read the docs for self-hosting. If "self-hosted" requires their cloud anyway (a managed control plane), it's not really self-hosted. If self-hosted means "Docker + Postgres + your VPS," that's the real article.

Red flags:

• "Self-hosted" that requires an account on the vendor's cloud for licensing or features
• Self-hosted version missing features the SaaS version has (Strapi Enterprise gating RBAC, content history)
• License-server check-ins required for self-hosted operation (your CMS dies if the vendor's license server goes down)
• Self-hosted but with no documented backup or disaster-recovery story

What good looks like:

• Truly standalone: clone repo, set env vars, run with Docker or PM2, done
• Open-source license (MIT, Apache, BSL-with-clear-conversion) so you can fork if needed
• Your data lives in your database (Postgres, MySQL, MongoDB) on infrastructure you chose
• No required telemetry or phone-home checks
• Documented backup and migration paths

For regulated workloads, see self-hosted CMS and GDPR: data sovereignty in 2026 — the compliance benefits often justify the operational cost. For the broader self-hosted-vs-SaaS framing, self-hosted CMS vs SaaS CMS and the best self-hosted CMS platforms in 2026 cover the full picture.

10. Migration Path Off the Platform

What to evaluate: How hard it would be to leave this CMS in 3 years if you needed to.

Sounds defensive; isn't. CMS migrations happen — repricing, feature deprecation, acquisition pivots, team changes. The harder it is to leave, the more leverage the vendor has at every renewal. Evaluate the exit door before you walk through the entrance.

How to test: Look at the export tooling. Can you export all content, including media, in a structured format? Are there documented migration guides for the major destinations (WordPress, Sanity, Strapi)? Is the data shape standardized enough that you could write your own export?

Red flags:

• Export tooling buried in support pages, not the main docs
• Export that returns the data but loses media URLs, references, or revision history
• No bulk export — only per-document API calls (slow at scale, hits rate limits)
• Custom rich-text formats that don't convert cleanly to Markdown or HTML
• "Export available on Enterprise tier only"

What good looks like:

• Bulk export to a standard format (NDJSON, JSON, SQL dump) included on every tier
• Media library exportable with reference paths intact
• Documented migration guides or third-party tools for common destinations
• Open data formats — your content isn't locked in a vendor-specific structure

The framework-agnostic CMS migration guide for developers covers the broader playbook. For source-specific migration paths, migrate from Contentful, migrate from Sanity, and migrate from Strapi cover the popular departures.

How to Run a Real Evaluation

The 10-point checklist is the framework. Here's the process:

1. Score each item as critical / important / nice-to-have for your project. Don't skip this — the weighting is what makes the checklist useful.
2. Narrow to 2-3 candidates based on rough fit. Don't run the full evaluation on 10 platforms.
3. Allocate 4-6 hours per candidate for hands-on testing. Marketing pages and 30-minute demos don't surface the issues.
4. Test with the actual content team, not just engineering. Editor UX is where most picks go wrong.
5. Project year-3 pricing with realistic growth assumptions, not the entry-tier numbers.
6. Run a 1-week trial on the top candidate. Build a real page, edit real content, query the API, do a localized variant if relevant. The 1-week trial is what separates "demo-good" from "production-good."
7. Document the decision with the scoring filled in. When the renewal comes up in 3 years, future-you wants the original reasoning.

Most teams who do this picking process pick a CMS they're happy with at year 1. Most teams who skip it end up migrating at year 2.

What to Do About It

If you're in the final week before signing a headless CMS contract, run all 10 items on your top candidate. The deciding criteria are usually data model fit, editor UX, and pricing-at-scale; everything else is recoverable.

If you're not yet at the final-week stage:

• For broader research, read what is a headless CMS and the 7 benefits of headless CMS for modern websites
• For the React-specific picture, the best CMS for React developers in 2026
• For the WordPress-vs-modern question, WordPress vs modern CMS: honest feature comparison
• For the self-hosted-specific picture, best self-hosted CMS platforms in 2026

If your stack matches Laravel + React + shadcn/ui and you're considering UnfoldCMS, see pricing, book a demo, or read the modern CMS stack: Laravel + React + Inertia. We're a self-hosted modern CMS by design — items 8 and 9 of the checklist are our design center, items 1 and 2 are where we're investing, and items 3 and 4 are where we know we're still maturing as the product grows.

FAQ

What's the most important thing to evaluate when choosing a headless CMS?

Data model fit, editor UX, and pricing-at-scale, in that order for most teams. Data model fit because workarounds for unsupported content shapes compound; editor UX because content people will rebel against an admin they hate; pricing-at-scale because year-3 SaaS bills are usually 3-5x year-1 bills. The other items matter, but these three are the ones where the wrong call is hardest to recover from.

How long should a headless CMS evaluation take?

For a serious project, 2-4 weeks. Allocate 4-6 hours per candidate for hands-on testing, 1 week of trial use on your top pick, and time for the content team to actually try it. Teams that compress this into a single afternoon end up replatforming within 18 months. The migration cost dwarfs the evaluation time savings.

Should I pick a SaaS or self-hosted headless CMS?

Self-hosted wins on data ownership, pricing predictability, and compliance flexibility. SaaS wins on operational simplicity, edge delivery, and feature breadth at the high end. The deciding factor is usually team capacity — do you have someone who can operate a Linux server with backups and security patching? If yes, self-hosted is usually better long-term. If no, mature SaaS is safer.

What should I look for in a headless CMS API?

REST and GraphQL both available, generated TypeScript types from schema, draft-mode preview that works with your framework's draft mode, sensible rate limits, field selection (fetch only what you need), and consistent auth across live/draft. The presence of these features differentiates "demo-good" CMSes from production-grade ones.

Can I migrate off a headless CMS later if it doesn't work out?

Yes, but the cost varies widely. Some CMSes (Sanity, Strapi, Directus) have clean export tooling that makes migration a normal project. Others (some smaller SaaS players) make export painful enough that "stuck on the platform" is the practical outcome. Item #10 of this checklist is specifically about evaluating the exit door before you walk through the entrance — it's the most under-weighted item in most evaluations.

Sources & Methodology

This checklist draws on:

• First-hand evaluation projects — UnfoldCMS team has run CMS evaluations across multiple projects; the 10 items reflect what we actually tested
• Migration project retros — the post-mortems from teams who picked the wrong CMS and had to switch (see framework-agnostic CMS migration guide for developers)
• Pricing pages — checked May 2026 for entry-tier and scaling pricing (sanity.io/pricing, contentful.com/pricing, hygraph.com/pricing, datocms.com/pricing, storyblok.com/pricing)
• Vendor documentation — official docs for self-hosting, draft mode, localization, version history, image transformations
• Community signals — Reddit r/webdev, r/reactjs, r/headlesscms threads on CMS evaluation 2024-2026

Disclosure: UnfoldCMS is our product. The 10-point framework is intentionally vendor-neutral — items 8 and 9 (pricing, self-host) lean toward self-hosted CMSes because that's our category, but the other items are CMS-agnostic. The "what good looks like" examples cite SaaS competitors honestly when they're better at a specific item (Sanity for image pipelines, Storyblok for visual editing, DatoCMS for EU residency).

This checklist is for the buying decision — the post-buy work (migration, schema design, integration) is covered in the linked migration guides and platform-specific posts. For project-specific consulting, talk to a CMS consultant; this post is a framework, not legal or contractual advice.