JSS components for rendering Sitecore fields in Next.js applications
JSS for Next.js provides components that help you render Sitecore fields in your Next.js applications.
The following table shows the correspondence between Sitecore field types and JSS Next.js components:
Sitecore field type |
JSS Next.js component |
---|---|
Date |
|
File |
|
Image |
|
General Link |
|
Single-Line Text, Multi-Line Text, or numeric types |
|
Rich Text |
|
The following is a list of supported components with examples of using them. In the examples, field data is provided by a Placeholder
component.
Date
The Date
component helps render date and time content fields in JSS applications.
The Date
component has the following properties:
Name |
Description |
---|---|
|
Required. The field you want to render. It must be a Sitecore Date type. The field data includes the following properties:
|
|
The name of the HTML element wrapping the date value. Default: |
|
Explicitly enable/disable inline editing. If Default: |
|
A function that receives the field value as a parsed JavaScript Date object and returns the value to render in the wrapping |
|
If Metadata Edit Mode is enabled and |
Usage
To render a date field, you must import it into your component:
import { DateField } from '@sitecore-jss/sitecore-jss-nextjs';
You can use the component as follows:
-
To render a simple date field:
RequestResponse<DateField field={props.fields.date} />
-
To render a datetime field:
RequestResponse<DateField field={props.fields.dateTime} />
-
To render a date as a UTC-formatted string:
RequestResponse<DateField field={props.fields.date} render={(date) => date.toUTCString()} />
NoteThe
render
property is ignored in editing mode.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:RequestResponse<DateField field={props.fields.date} render={(date) => date.toLocaleDateString()} /> <DateField field={props.fields.dateTime} render={(date) => <em>{date.toLocaleString()}</em>} />
File
The File
component renders a file link.
The File
component has the following properties:
Name |
Description |
---|---|
|
Required. The route field you want to render. It represents a Sitecore File type with the properties |
|
A React Node, populating the rendered |
The File field does not support inline editing with the Experience Editor. However, it can be edited using the default field editor on components.
Usage
To render the file field, you must import it into your component:
import { File } from '@sitecore-jss/sitecore-jss-nextjs';
You can use the component as follows:
-
To render a simple file link:
RequestResponse<File field={props.fields.file} />
-
To render a file link that opens in a new tab with custom anchor text:
RequestResponse<File field={props.fields.file} target="_blank"> View file </File>
Image
The Image
component lets you render editable, responsive images.
The Image
component has the following properties:
Name |
Description |
---|---|
|
Required. The field data includes the following properties:
|
|
A Boolean value you can use to enable or disable the inline editing of the image. Default: |
|
An array of |
|
An array of |
|
A custom regular expression that finds the media URL prefix to be replaced by |
|
If Metadata Edit Mode is enabled and |
When using the imageParams
or srcSet
properties, your image parameters must be white-listed on the server for security purposes.
You can pass additional properties to the component. For example, you can specify values for the native image sizes
attribute to enable responsive server-side rendered images.
Usage
To use the Image
component, you must import it into your component:
import { Image } from '@sitecore-jss/sitecore-jss-nextjs';
You can use the Image
component to render:
-
A simple image:
RequestResponse<Image media={props.fields.sample1} />
-
A responsive image:
RequestResponse<Image field={props.fields.sample2} srcSet={[{ mw: 300 }, { mw: 100 }]} sizes="(min-width: 960px) 300px, 100px" className="img-fluid" />
-
An image with advanced configuration. For example, the following sample renders an image that is not editable in a Sitecore content and layout editor like the Experience Editor. The image is resized server-side based on the
imageParams
property:RequestResponse<Image field={props.fields.sample2} editable={false} imageParams={{ mw: 100, mh: 50 }} height="50" width="94" data-sample="other-attributes-pass-through" />
Link
The Link
component helps you render the content of the General Link Sitecore field.
The component checks if the link in the Sitecore field is internal, and if so, it renders the link using the Next.js Link component (next/link
). Otherwise, it renders a Link component.
The Link
component has the following properties:
Name |
Description |
---|---|
|
Required. The route field you want to render. It must be a Sitecore General Link field type. The field data includes the following properties:
|
|
Indicates whether to use the editor or Sitecore-formatted HTML output. Default: Note If using editable output from Sitecore, Link creates a wrapper span around the Sitecore-provided markup and applies host element attributes to this span. |
|
A Regex pattern for identifying internal links. Default: |
|
A Boolean expression that enables or disables the display of a link description even when children exist. Note This setting is ignored in the Sitecore Experience Editor due to technical limitations, and the description is always rendered. |
|
If Metadata Edit Mode is enabled and |
Usage
To use the Link
field helper component, you must import it into your component:
import { Link } from '@sitecore-jss/sitecore-jss-nextjs';
You can use the Link
component to render:
-
External links:
RequestResponse<Link field={props.fields.externalLink} />
-
Internal links with HTML or other components:
RequestResponse<Link field={props.fields.internalLink}> <em>HTML</em> or other components can be used within link renderers, for example, links to images. </Link>
-
Email links:
RequestResponse<Link field={props.fields.emailLink} />
-
A content parameters link:
RequestResponse<Link field={props.fields.paramsLink} />
The link component accepts additional properties or attributes. For example:
<Link
field={props.fields.externalLink}
showLinkTextWithChildrenPresent={true}
className="font-weight-bold"
data-otherattributes="pass-through-to-anchor-tag"
/>
In the Experience Editor, a link description is always rendered in editing mode. If the link has any children, they are rendered as siblings to the link description.
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 |
---|---|
|
Required. The field you want to render. The field data includes the following properties:
|
|
The name of the HTML element you want to wrap the text value. Default: |
|
Indicates whether to use the editor or Sitecore-formatted HTML output. Default: |
|
Enables or disables HTML encoding of the output value. A false value also implies Default: |
|
If Metadata Edit Mode is enabled and |
For a Multi-line Text field type, in the provided editable value, any line breaks are replaced by <br />
. When using the non-editable value, you can process field.value
to replace JSON newlines with the desired markup or use a CSS white-space value such as pre-wrap.
Usage
To use the Text
component, you must import it into your component:
import { Text } from '@sitecore-jss/sitecore-jss-nextjs';
You can render:
-
A text field with default options:
RequestResponse<Text field={props.fields.sample} />
-
A non-editable text field with a custom tag, CSS classes, and custom attributes:
RequestResponse<Text field={props.fields.sample2} tag="section" editable={false} encode={false} className="font-weight-bold" data-sample="other-attributes-pass-through" />
If you want to render the raw value of a Sitecore text field, add the getFieldValue
function to your import statement. You can then inspect the raw value in your application. For example:
<div>Raw value (not editable): {getFieldValue(props.fields, 'sample')}</div>
RichText
The RichText
component helps you render Sitecore Rich Text fields.
The RichText
component has the following properties:
Name |
Description |
---|---|
|
Required. The field you want to render. The field data includes the following properties:
|
|
The name of the HTML element you want to wrap the text value. Default: |
|
Indicates whether to use the editor or Sitecore-formatted HTML output. Default: |
|
If Metadata Edit Mode is enabled and |
Usage
To use the RichText
component, you must import it into your component:
import { RichText } from '@sitecore-jss/sitecore-jss-nextjs';
You can render:
-
A field with default options:
RequestResponse<RichText field={props.fields.sample} />
-
A non-editable rich-text field with a custom tag, CSS classes, and custom attributes:
RequestResponse<RichText field={props.fields.sample2} tag="section" editable={false} className="font-weight-bold" data-sample="other-attributes-pass-through" />