ACF + TypeScript: Building Type-Safe Flexible Content

Advanced Custom Fields (ACF) is the go-to solution for flexible WordPress content. But in a TypeScript headless setup, losing type safety on your custom fields is a major pain point.

FlatWP solves this with automatic TypeScript generation from your ACF field groups.

The Problem

When you query ACF fields through GraphQL, you get untyped data:

const hero = page.acf.hero; // any type - no autocomplete, no safety

This means runtime errors, no IDE support, and constant trips to the WordPress admin to check field names.

The FlatWP Solution

Our WordPress plugin exposes ACF schemas as structured JSON. Our codegen tool transforms these into TypeScript interfaces:

interface HeroBlock {
  heading: string;
  subheading: string;
  image: {
    url: string;
    alt: string;
  };
  ctaText: string;
  ctaUrl: string;
}

Now your components are fully typed:

export function HeroBlock({ fields }: { fields: HeroBlock }) {
  return (
    <section>
      <h1>{fields.heading}</h1>
      <p>{fields.subheading}</p>
      {/* TypeScript knows exactly what fields exist */}
    </section>
  );
}

Flexible Content Blocks

ACF’s Flexible Content field type is perfect for page builders. FlatWP provides a block renderer pattern:

const blockComponents = {
  hero: HeroBlock,
  features: FeaturesBlock,
  testimonial: TestimonialBlock,
};

export function BlockRenderer({ blocks }: { blocks: ACFBlock[] }) {
  return blocks.map((block) => {
    const Component = blockComponents[block.layout];
    return <Component key={block.id} fields={block.fields} />;
  });
}

Coming in FlatWP Pro

The Pro version will include a library of 20+ pre-built ACF blocks with matching Shadcn components. Hero sections, feature grids, testimonials, pricing tables – all typed, styled, and ready to use.

You’ll be able to build complex page layouts in WordPress while maintaining full TypeScript safety in your React components.