Media & Blocks

This page documents the MediaFile and BlocksContent types generated for Strapi media attributes and the Blocks rich text editor.

MediaFile

The MediaFile interface is generated for all Strapi media attributes. It represents a single uploaded file with its metadata.

export interface MediaFile {
    id: number
    name: string
    alternativeText: string | null
    caption: string | null
    width: number | null
    height: number | null
    formats: unknown
    hash: string
    ext: string
    mime: string
    size: number
    url: string
    previewUrl: string | null
    provider: string
    createdAt: string
    updatedAt: string
}

Field Reference

Field	Type	Description
id	number	Database ID of the media entry
name	string	Original file name
alternativeText	string | null	Alt text for accessibility
caption	string | null	Optional caption
width	number | null	Image width in pixels (null for non-images)
height	number | null	Image height in pixels (null for non-images)
formats	unknown	Responsive image formats generated by Strapi (thumbnail, small, medium, large)
hash	string	Unique hash of the file
ext	string	File extension (e.g., .jpg, .pdf)
mime	string	MIME type (e.g., image/jpeg, application/pdf)
size	number	File size in kilobytes
url	string	URL to access the file
previewUrl	string | null	Preview URL (used by some providers)
provider	string	Storage provider (e.g., local, aws-s3, cloudinary)
createdAt	string	ISO datetime of upload
updatedAt	string	ISO datetime of last update

Single vs. Multiple Media

Strapi media attributes can be configured as single or multiple:

Configuration	Base Type	Input Type
Single media (required)	MediaFile	number | null
Single media (not required)	MediaFile | null	number | null
Multiple media	MediaFile[]	number[] | null

Using Media with Populate

Media fields require populate to be included in the response. Without populate, media fields are not present on the returned type.

// Without populate — no media fields in the type
const article = await strapi.articles.findOne('abc123')
// article.cover  <-- does not exist on type

// With populate — media fields are included
const article = await strapi.articles.findOne('abc123', {
    populate: { cover: true },
})
// article.cover?.url  <-- fully typed as MediaFile | null

You can also select specific media fields:

const article = await strapi.articles.findOne('abc123', {
    populate: {
        cover: { fields: ['url', 'alternativeText', 'width', 'height'] },
    },
})

Accessing Image URLs and Formats

const article = await strapi.articles.findOne('abc123', {
    populate: { cover: true },
})

if (article.cover) {
    // Direct URL
    const imageUrl = article.cover.url

    // Alt text for <img> tag
    const alt = article.cover.alternativeText ?? ''

    // Dimensions
    const { width, height } = article.cover

    // Responsive formats (thumbnail, small, medium, large)
    const formats = article.cover.formats as Record<
        string,
        {
            url: string
            width: number
            height: number
        }
    > | null

    if (formats?.thumbnail) {
        const thumbnailUrl = formats.thumbnail.url
    }
}

TIP

The formats field is typed as unknown because its structure depends on your Strapi media configuration. Cast it to a more specific type if you know your format settings.

Media in Input Types

When creating or updating entries, media fields accept numeric IDs (not file objects). Upload the file first via Strapi's upload API, then reference it by ID.

// Create with media by ID
await strapi.articles.create({
    title: 'New Article',
    cover: 42, // single media -> number
    gallery: [42, 43], // multiple media -> number[]
})

// Clear a media field
await strapi.articles.update('abc123', {
    cover: null,
})

BlocksContent

The BlocksContent type represents content from Strapi's Blocks rich text editor (the v2 rich text field introduced in Strapi v5). It is a structured array of block objects.

export type BlocksContent = Block[]

Block Types

export type Block =
    | ParagraphBlock
    | HeadingBlock
    | QuoteBlock
    | CodeBlock
    | ListBlock
    | ImageBlock

ParagraphBlock

export interface ParagraphBlock {
    type: 'paragraph'
    children: InlineNode[]
}

HeadingBlock

export interface HeadingBlock {
    type: 'heading'
    level: 1 | 2 | 3 | 4 | 5 | 6
    children: InlineNode[]
}

QuoteBlock

export interface QuoteBlock {
    type: 'quote'
    children: InlineNode[]
}

CodeBlock

export interface CodeBlock {
    type: 'code'
    language?: string
    children: InlineNode[]
}

ListBlock

export interface ListBlock {
    type: 'list'
    format: 'ordered' | 'unordered'
    children: ListItemBlock[]
}

export interface ListItemBlock {
    type: 'list-item'
    children: InlineNode[]
}

ImageBlock

export interface ImageBlock {
    type: 'image'
    image: {
        name: string
        alternativeText?: string | null
        url: string
        caption?: string | null
        width?: number
        height?: number
        formats?: unknown
        hash: string
        ext: string
        mime: string
        size: number
        previewUrl?: string | null
        provider: string
        createdAt: string
        updatedAt: string
    }
    children: InlineNode[]
}

Inline Nodes

All block types contain children arrays of inline nodes:

export type InlineNode = TextNode | LinkInline

TextNode

export interface TextNode {
    type: 'text'
    text: string
    bold?: boolean
    italic?: boolean
    underline?: boolean
    strikethrough?: boolean
    code?: boolean
}

LinkInline

export interface LinkInline {
    type: 'link'
    url: string
    children: TextNode[]
}

Rendering Blocks on the Frontend

BlocksContent is a structured data format. You need a renderer to convert it to HTML or React elements. Strapi provides an official renderer for React:

npm install @strapi/blocks-react-renderer

import { BlocksRenderer } from '@strapi/blocks-react-renderer'
import type { BlocksContent } from './dist'

function ArticleBody({ content }: { content: BlocksContent }) {
    return <BlocksRenderer content={content} />
}

INFO

The BlocksContent type is only generated when your schema contains at least one blocks type attribute. If your Strapi project uses only the classic richtext (Markdown) type, that field is typed as string instead.

Blocks vs. RichText

Attribute Type	Generated TypeScript Type	Format
richtext (Markdown)	string	Raw Markdown string
blocks (Blocks editor)	BlocksContent	Structured JSON array

The blocks type provides a structured, renderable format, while richtext is a plain Markdown string that you parse and render yourself.