Skip to main content
t3headless
DEVELOPER DOCUMENTATION HUB TYPO3 v13 / v14

T3Headless Documentation & Quickstart Guide.

Highlighted essentials from our official user guide: TYPO3 Composer installation, YAML API setup, Next.js frontend configuration, visual elements, and React template conventions.

01 / TYPO3 INSTALLATION

Extension Install & Base Configuration

Install EXT:t3headless via Composer (mandatory for TYPO3 v14+; TER installation is supported up to TYPO3 v13), disable cHash 404 errors, and include the TypoScript templates in the required sequence.

  • Admin Tools > Settings > Configure Installation-Wide Options: set [FE][pageNotFoundOnCHashError] to false.
  • Composer automatically installs the required Container Content Elements dependency.
  • In Site Management > TypoScript (Advanced Options), remove default Setup TypoScript and include in order: fluid_styled_content, form, seo, news, t3headless.
# 1. Install EXT:t3headless via Composer (mandatory for TYPO3 v14+, recommended for v13)
composer require t3element/t3headless

# 2. Setup extensions & flush caches
vendor/bin/typo3 extension:setup
vendor/bin/typo3 cache:flush

# Note: TER download (Admin Tools > Extensions > Get Extension -> "t3headless")
# is supported up to TYPO3 v13 only.
02 / API & ACTIVATION

YAML API Configuration & License Activation

Import the T3Headless API routes into your site config.yaml and activate the extension inside TYPO3 via Web > t3headless using either a store license key or instant free registration.

  • Add the API resource import to your site config/sites/<site>/config.yaml file.
  • Navigate to Web > t3headless > Get Started in the TYPO3 backend.
  • Choose "Activate License" with your T3Element store key, or register directly after installation to receive a free license key by email.
# config/sites/<your-site>/config.yaml
imports:
  - resource: 'EXT:t3headless/Configuration/Yaml/default.yaml'

# Verify JSON API endpoint once configured:
# curl -i https://api.example.com/?type=834
03 / NEXT.JS FRONTEND

Next.js Frontend Package (t3headless-frontend)

Set up the production-ready Next.js frontend package, connect it to TYPO3 via config.js, and manage global Header/Footer pages, Logo, Favicon, Fonts, and CSS/JS directly from Theme Options > Header.

  • Prerequisites: Next.js supported server with Node.js 18.17+ (recommended v20.11.0), plus npm or yarn.
  • Configure API_LICENSE_KEY and API_KEY from your activation email inside config.js.
  • Run initial setup once (yarn setup), rebuild theme & UI elements anytime with yarn themebuild, then build and start.
# 1. Clone the Next.js frontend package
git clone https://github.com/milancrayon/t3headless-frontend
cd t3headless-frontend

# 2. Add API_LICENSE_KEY and API_KEY in config.js

# 3. Run initial setup (required once)
yarn setup          # or: npm run setup

# 4. Build theme configuration & generated UI elements
yarn themebuild     # or: npm run themebuild

# 5. Build and launch production server (default port 3000)
yarn build && yarn start
04 / VISUAL ELEMENTS

Building Container & Custom Elements

Create multi-column Container Elements and custom content blocks (such as Sliders, Teaser Boxes, and CTAs) using the guided 3-tab workflow (Info, Fields, Template) directly inside TYPO3.

  • Container Elements (t3headless > Elements > Container Elements): click "New Container Element", add columns via "+ Add Column", and customize the generated template.
  • Custom Elements (t3headless > Elements > Custom Elements): click "+ Create New Element", drag and drop fields, and use the "Repeating" field for sliders or FAQs.
  • Theme Options > Header: upload Logo (with optional custom width/height), Favicon, Fonts, CSS/JS, and assign global Header pages.
# Guided 3-Tab Builder Workflow in TYPO3 Backend:
#
# Container Elements: t3headless > Elements > Container Elements > New Container Element
# Custom Elements:    t3headless > Elements > Custom Elements    > + Create New Element
#
#   Tab 1: Info      -> Title, Short Title, Description
#   Tab 2: Fields    -> Add Columns / Drag-and-Drop Fields / Repeating Items
#   Tab 3: Template  -> Edit React/Next.js JSX template directly
05 / REACT & NEXT.JS NOTES

React / Next.js Template Guidelines

Follow these essential conventions when editing T3Headless React/Next.js component templates, including built-in components that require no manual imports.

  • Use className instead of the standard HTML class attribute.
  • Use Next.js <Link> instead of <a> (auto-available in T3Headless templates; no import needed).
  • Use <Nimage> instead of <img> (custom wrapper over Next.js Image; mandatory props: key, immg, data; no import needed).
  • Access React-Bootstrap and Swiper components via the "All." prefix: <All.Accordion>, <All.Slider>, and <All.SliderItem>.
{/* 1. Next.js Link & className (no import needed) */}
<Link href="/contact" className="btn-primary">Get Started</Link>

{/* 2. T3Headless Nimage component (no import needed) */}
{_data?.images?.map((immg: any, index: number) => (
  <Nimage
    key={_data?.uid + immg?.url + index}
    immg={immg}
    data={data}
    width={500}
    height={500}
    className="w-100 h-auto"
    alt="Preview"
  />
))}

{/* 3. React-Bootstrap & Swiper via All.* prefix */}
<All.Accordion defaultActiveKey="0">...</All.Accordion>
<All.Slider slidesPerView={1} navigation={true}>
  <All.SliderItem>...</All.SliderItem>
</All.Slider>
INTERACTIVE JSON SCHEMA SANDBOX

Inspect JSON Responses

Interactive Headless TYPO3 → Component Inspector
GET https://api.example.com/?type=834 200 OK • JSON
{
  "id": 1,
  "slug": "/",
  "title": "Example Headless TYPO3 Site",
  "meta": {
    "title": "Example Brand | Headless TYPO3",
    "canonical": "https://www.example.com/",
    "robots": { "index": true, "follow": true }
  },
  "content": {
    "colPos0": [
      {
        "id": 104,
        "type": "t3element_hero_banner",
        "colPos": 0,
        "appearance": { "layout": "split-grid-2col" },
        "content": {
          "eyebrow": "HEADLESS CONTENT BLOCK",
          "headline": "Structured content delivered directly from TYPO3 JSON.",
          "ctaPrimary": { "label": "Get Started", "href": "/get-started" },
          "metrics": { "apiSpeedMs": 18, "uptime": "99.99%" }
        }
      }
    ]
  }
}
Hydrated UI Component <HeroBanner />
LIVE PREVIEW

Hero Banner Content Block

Renders the 2-column hero section and structured CTA fields directly from colPos0 JSON.

T3Element Runtime Guarantees

TTFB: 14msZero Fluid OverheadAuto-Typed Props
OFFICIAL DOCUMENTATION & USER GUIDE

Explore the complete step-by-step T3Headless user guide.

Read every walkthrough with backend screenshots, theme options, container and custom element tutorials, and React/Next.js template references on our official documentation portal.