Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alineacms/alinea/llms.txt

Use this file to discover all available pages before exploring further.

Alinea’s link and media fields create typed references between content entries and the files stored in your media library. Unlike raw string foreign keys, each link field returns a fully resolved object — with the linked entry’s title, URL, and any extra fields you configure. All link type definitions are exported from alinea.
Imports
import {Field} from 'alinea'
import type {EntryLink, ImageLink, FileLink, Link, UrlLink} from 'alinea'
At query time, Alinea resolves all references automatically. The raw stored value is an EntryReference or UrlReference object, but the query layer replaces it with the fully populated typed object described in this page. Import EntryReference and UrlReference from alinea if you need to work with the raw reference shape.

​
Field.entry

Field.entry links to another content entry in your workspace. The resolved value is an EntryLink object containing the linked entry’s entryId, entryType, title, path, and href.
Using Field.entry
import {Config, Field} from 'alinea'

export const BlogPost = Config.document('Blog post', {
  fields: {
    // Basic entry link
    relatedPost: Field.entry('Related post'),

    // Filtered to a specific type
    category: Field.entry('Category', {
      condition: {_type: 'Category'},
      help: 'Select a category page'
    }),

    // Scoped to a specific part of the content tree
    featuredPage: Field.entry('Featured page', {
      location: {workspace: 'main', root: 'pages'}
    })
  }
})
The EntryLink type shape:
EntryLink type
interface EntryLink<InferredFields = undefined> {
  entryId: string
  entryType: string
  title: string
  path: string
  href: string
  fields: InferredFields
}

​
Attaching extra fields

Pass a fields object to collect additional data at the time the link is created (for example, a custom label for the link):
Entry link with extra fields
import {Config, Field} from 'alinea'

export const Navigation = Config.document('Navigation', {
  fields: {
    primaryLink: Field.entry('Primary link', {
      fields: {
        label: Field.text('Link label', {width: 0.5}),
        openInNewTab: Field.check('Open in new tab')
      }
    })
  }
})

​
Multiple entry links

Use Field.entry.multiple to allow selecting more than one entry:
Multiple entry links
import {Config, Field} from 'alinea'

export const CollectionPage = Config.document('Collection page', {
  fields: {
    items: Field.entry.multiple('Featured items', {
      condition: {_type: 'Product'}
    })
  }
})
​
condition
object
A filter object that limits which entries can be selected. For example, {_type: 'Article'} restricts the picker to entries of that type.
​
location
object
Restricts the entry picker to a specific workspace and root. Useful for multi-workspace setups.
​
pickChildren
boolean
When true, only direct children of the currently edited entry are shown in the picker.
​
fields
FieldsDefinition
Additional fields collected alongside the link reference. The data is stored inside the fields property of the resolved EntryLink.
​
help
ReactNode
Instructional text below the field label.
​
inline
boolean
Compact, borderless rendering of the link field.
​
width
number
Fractional form width (0–1).

​
Field.image

Field.image opens the media library filtered to image files. The resolved value is an ImageLink object with image-specific metadata such as dimensions, average colour, and thumb hash for blur placeholders.
Using Field.image
import {Config, Field} from 'alinea'

export const Hero = Config.document('Hero', {
  fields: {
    image: Field.image('Hero image', {
      help: 'Recommended: 1600×900 pixels'
    }),
    gallery: Field.image.multiple('Gallery images')
  }
})
The ImageLink type shape:
ImageLink type
interface ImageLink<InferredFields = undefined> {
  title: string
  src: string
  url: string
  extension: string
  size: number
  hash: string
  width: number
  height: number
  averageColor: string
  thumbHash: string
  focus: {x: number; y: number}
  fields: InferredFields
}
Use Field.image.multiple to allow multiple image selections. The result is an array of ImageLink objects.
​
help
ReactNode
Instructional text displayed below the label.
​
fields
FieldsDefinition
Extra fields attached to each image selection (e.g. an alt-text field).
​
inline
boolean
Compact, borderless rendering of the image picker.
​
width
number
Fractional form width (0–1).

​
Field.file

Field.file opens the media library filtered to non-image files. The resolved value is a FileLink object with the file’s title, href, extension, and byte size.
Using Field.file
import {Config, Field} from 'alinea'

export const Download = Config.document('Download', {
  fields: {
    file: Field.file('Attachment', {
      help: 'PDF, ZIP, or other document'
    }),
    files: Field.file.multiple('Multiple attachments')
  }
})
The FileLink type shape:
FileLink type
interface FileLink<InferredFields = undefined> {
  title: string
  href: string
  extension: string
  size: number
  fields: InferredFields
}
​
help
ReactNode
Instructional text below the label.
​
fields
FieldsDefinition
Extra fields attached to each file selection.
​
inline
boolean
Compact, borderless rendering of the file picker.
​
width
number
Fractional form width (0–1).

​
Field.link

Field.link is a polymorphic field: it allows the editor to pick either an internal entry, an external URL, or a file from the media library. The resolved value is the union type Link<Fields>, which is EntryLink | UrlLink | FileLink.
Using Field.link
import {Config, Field} from 'alinea'

export const CallToAction = Config.document('Call to action', {
  fields: {
    // Single polymorphic link
    cta: Field.link('Call to action link'),

    // Multiple polymorphic links
    relatedLinks: Field.link.multiple('Related links', {
      fields: {
        label: Field.text('Link label', {width: 0.5})
      }
    })
  }
})
The Link type:
Link union type
// Exported from 'alinea'
type Link<InferredFields> =
  | EntryLink<InferredFields>
  | UrlLink<InferredFields>
  | FileLink<InferredFields>
Discriminate on the _type field ("entry" | "url" | "file") when you need to handle each variant differently.
​
fields
FieldsDefinition
Extra fields collected for every link variant (entry, URL, or file).
​
condition
object
Restricts which entries appear in the entry picker pane of the link dialog.
​
pickChildren
boolean
When true, only direct children of the currently edited entry are shown in the entry picker pane.
​
help
ReactNode
Instructional text below the label.
​
inline
boolean
Compact, borderless rendering of the link field.
​
width
number
Fractional form width (0–1).

​
Field.url

Field.url provides a URL input backed by the URL picker dialog. The editor can paste a URL or open a dialog to select and configure it. The resolved value is a UrlLink object.
Using Field.url
import {Config, Field} from 'alinea'

export const SocialLinks = Config.document('Social links', {
  fields: {
    twitter: Field.url('Twitter / X'),
    linkedin: Field.url('LinkedIn', {help: 'Your LinkedIn profile URL'}),
    urls: Field.url.multiple('Additional links')
  }
})
The UrlLink type shape:
UrlLink type
interface UrlLink<InferredFields = undefined> {
  href: string
  title: string
  target: string
  fields: InferredFields
}
Use Field.url.multiple to allow multiple URL entries.
​
help
ReactNode
Instructional text below the label.
​
fields
FieldsDefinition
Extra fields attached to each URL entry.
​
inline
boolean
Compact, borderless rendering of the URL field.
​
width
number
Fractional form width (0–1).

​
Full example

Link fields combined in one type
import {Config, Field} from 'alinea'

export const PageLinks = Config.document('Link fields', {
  fields: {
    externalLink: Field.url('External link'),
    entry: Field.entry('Internal link'),
    entryWithCondition: Field.entry('Articles only', {
      condition: {_type: 'Article'}
    }),
    mixedLinks: Field.link.multiple('Mixed links'),
    hero: Field.image('Hero image'),
    gallery: Field.image.multiple('Gallery'),
    download: Field.file('Download'),
    withFields: Field.entry('Link with label', {
      fields: {
        label: Field.text('Custom label', {width: 0.5})
      }
    })
  }
})

Build docs developers (and LLMs) love

Get started for freeTalk to us