Concepts

Content SDK
Concepts

Components for rendering Sitecore fields

Version: 2.x

Content SDK provides components that help you render Sitecore fields in your Next.js applications.

The following table shows the correspondence between Sitecore field types and Content SDK components:

Sitecore field type	Content SDK component
Date	`DateField`
File	`File`
Image	`Image`. You can also use the `NextImage` component.
General Link	`Link`
Single-Line Text, Multi-Line Text, or numeric types	`Text`
Rich Text	`RichText`

Import all of these components from @sitecore-content-sdk/nextjs. Link and RichText have Next.js-specific implementations there that add internal link detection, prefetching, and client-side routing on top of the base components in @sitecore-content-sdk/react. DateField, Text, File, and Image are the same components re-exported from @sitecore-content-sdk/react.

The following sections describe the supported components with usage examples. In the examples, props.fields is the component's field data, which the Placeholder component supplies from the layout data.

Date

The DateField component helps render date and time content fields.

The DateField component has the following properties:

Name	Description
`field`	Required. The field you want to render. It must be a Sitecore Date type. The field data includes the following properties: `value` - represents the raw field value from the Sitecore item. `metadata` - the field metadata that is exposed to allow editing in Pages.
`tag`	The name of the HTML element wrapping the date value. If omitted, the value is rendered without a wrapping element. Default: none
`editable`	Explicitly enable/disable inline editing. Default: `true`
`render`	A function that receives the field value as a parsed JavaScript `Date` object and returns the value to render in the wrapping `tag` of the component. It can be used to format the value for date and datetime localization.
`emptyFieldEditingComponent`	If the field has metadata and an empty value, the component specified here is rendered instead. If this is also empty, the default empty field component is rendered.

Usage

To render a date field, import it into your component:

import { DateField } from '@sitecore-content-sdk/nextjs';

You can use the component as follows:

To render a simple date field:
<DateField field={props.fields.date} />
To render a datetime field:
<DateField field={props.fields.dateTime} />
To render a date as a UTC-formatted string:
<DateField field={props.fields.date} render={(date) => date?.toUTCString()} />
The component provides direct access to the JS Date object for formatting purposes. Therefore, you can use it to render localized date and datetime strings as follows:
<DateField field={props.fields.date} render={(date) => date?.toLocaleDateString()} /> <DateField field={props.fields.dateTime} render={(date) => {date?.toLocaleString()}} />

File

The File component renders a file link.

The File component has the following properties:

Name	Description
`field`	Required. The field you want to render. It represents a Sitecore File type with the properties `src`, `title`, and `displayName`, either directly on `field` or on `field.value`.
`children`	A React node, populating the rendered `<a />` tag. The default value is the file's `title` or `displayName`.

Important

The File component doesn't support inline editing in Pages.

Usage

To render the file field, import it into your component:

import { File } from '@sitecore-content-sdk/nextjs';

You can use the component as follows:

To render a simple file link:
<File field={props.fields.file} />
To render a file link that opens in a new tab with custom anchor text:
<File field={props.fields.file} target="_blank"> View file </File>

Image

The Image component lets you render editable, responsive images. For details on the properties imageParams, srcSet, and mediaUrlPrefix and for examples of specifying media URL query parameters and rendering responsive images, see The Content SDK Image component.

Usage

To use the Image component, import it into your component:

import { Image } from '@sitecore-content-sdk/nextjs';

You can use the Image component to render a simple image:

<Image field={props.fields.sample1} />

Note

You can also use the NextImage component, which integrates with next/image.

Link

The Link component helps you render the content of the General Link Sitecore field.

The component checks whether the link in the Sitecore field is internal, and if so, renders it using the Next.js Link component (next/link), including prefetching. Otherwise, it renders a plain <a> tag.

The Link component has the following properties:

Name	Description
`field`	Required. The field you want to render. It must be a Sitecore General Link field type. The field data includes the following properties: `value` - an object containing link properties such as `href`, `text`, `target`, `title`, `class`, `querystring`, and `anchor`. `metadata` - the field metadata that is exposed to allow editing in Pages.
`editable`	Explicitly enable/disable inline editing. Default: `true`
`internalLinkMatcher`	A regex pattern for identifying internal links. Links matching the pattern are rendered with `next/link`; links to files (matched by file extension) are never treated as routes, regardless of this pattern. Default: `/^\//g`
`showLinkTextWithChildrenPresent`	A boolean that enables or disables the display of the link text even when children exist. Default: `false`
`renderChildrenWhenEmpty`	When `true`, renders an anchor element containing `children` even when the link field value is empty, instead of rendering nothing. Default: `false`
`prefetch`, `replace`, `scroll`, `shallow`, `passHref`, `as`, `onNavigate`	Passed through to `next/link` for internal links. `shallow`, `passHref`, and `as` apply only to the Pages Router. See the Next.js `Link` documentation for the App Router and Pages Router for details.
`emptyFieldEditingComponent`	If the field has metadata and an empty value, the component specified here is rendered instead. If this is also empty, the default empty field component is rendered.

Usage

To use the Link component, import it into your component:

import { Link } from '@sitecore-content-sdk/nextjs';

You can use the Link component to render:

External links:
<Link field={props.fields.externalLink} />
Internal links with HTML or other components:
<Link field={props.fields.internalLink}> HTML or other components can be used within link renderers, for example, links to images. </Link>
Email links:
<Link field={props.fields.emailLink} />

The Link component accepts additional properties or attributes. The following example displays the link text alongside the child element because showLinkTextWithChildrenPresent is true:

<Link
  field={props.fields.externalLink}
  showLinkTextWithChildrenPresent={true}
  className="font-weight-bold"
  data-otherattributes="pass-through-to-anchor-tag"
>
  <p>Link example</p>
</Link>

Text

The Text component helps you render Sitecore fields of type Single-Line Text, Multi-Line Text, or numeric fields.

The Text component has the following properties:

Name	Description
`field`	Required. The field you want to render. The field data includes the following properties: `value` - represents the raw field value from the Sitecore item. `metadata` - the field metadata that is exposed to allow editing in Pages.
`tag`	The name of the HTML element wrapping the text value. If omitted, the value is rendered without a wrapping element, except in editing mode or when `encode` is `false`, where `span` is used.
`editable`	Explicitly enable/disable inline editing. Default: `true`
`encode`	Enables or disables HTML encoding of the output value. Setting this to `false` also makes `editable: false`. Default: `true`
`emptyFieldEditingComponent`	If the field has metadata and an empty value, the component specified here is rendered instead. If this is also empty, the default empty field component is rendered.

For a Multi-line Text field type, line breaks in the value are replaced with   elements.

Usage

To use the Text component, import it into your component:

import { Text } from '@sitecore-content-sdk/nextjs';

You can render:

A text field with default options:
<Text field={props.fields.sample} />
A non-editable text field with a custom tag, CSS classes, and custom attributes:
<Text field={props.fields.sample2} tag="section" editable={false} encode={false} className="font-weight-bold" data-sample="other-attributes-pass-through" />
Important
Setting encode={false} outputs raw HTML. Use this option only with trusted content.

If you want to render the raw value of a Sitecore text field, import the getFieldValue function. You can then inspect the raw value in your application. For example:

import { getFieldValue } from '@sitecore-content-sdk/nextjs';

<div>Raw value (not editable): {getFieldValue(props.fields, 'sample')}</div>

RichText

The RichText component helps you render Sitecore Rich Text fields.

The component also handles internal links within the rendered HTML: it intercepts clicks on links matching internalLinksSelector and routes them client-side, and it prefetches them according to prefetchLinks.

The RichText component has the following properties:

Name	Description
`field`	Required. The field you want to render. The field data includes the following properties: `value` - represents the raw field value from the Sitecore item. `metadata` - the field metadata that is exposed to allow editing in Pages.
`tag`	The name of the HTML element you want to wrap the text value. Default: `div`
`editable`	Explicitly enable/disable inline editing. Default: `true`
`internalLinksSelector`	The CSS selector used to find internal links within the rendered HTML for prefetching and client-side routing. Default: `a[href^="/"]`
`prefetchLinks`	Controls the prefetch of internal links found via `internalLinksSelector`. This can be beneficial if you have `RichText` fields with large numbers of internal links in them. Can be one of the following: `true` - all matching links are prefetched as soon as the field renders. This provides the best overall performance but can incur higher resource costs. `'hover'` - links are individually prefetched when a user hovers their mouse over them. This offers some performance benefits without a substantial resource cost. `false` - links are never prefetched. Default: `true`
`emptyFieldEditingComponent`	If the field has metadata and an empty value, the component specified here is rendered instead. If this is also empty, the default empty field component is rendered.

Usage

To use the RichText component, import it into your component:

import { RichText } from '@sitecore-content-sdk/nextjs';

You can render:

A field with default options:
<RichText field={props.fields.sample} />
A non-editable rich text field with a custom tag, CSS classes, and custom attributes:
<RichText field={props.fields.sample2} tag="section" editable={false} className="font-weight-bold" data-sample="other-attributes-pass-through" />
A rich text field that prefetches its internal links only on hover, useful when a field contains many links:
<RichText field={props.fields.sample} prefetchLinks="hover" />

If you have suggestions for improving this article, let us know!