JSS components for rendering Sitecore fields in Next.js applications

Current version: 22.0

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

Date

File

File

Image

Image. Starting with version 20.1, you can also use the NextImage component.

General Link

Link

Single-Line Text, Multi-Line Text, or numeric types

Text

Rich Text

RichText

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

field

Required.

The field you want to render. It must be a Sitecore Date type. The field data has two properties:

  • The value property - represents the raw field value from the Sitecore item.

  • The editable property - contains the editable markup rendered when editing is enabled.

tag

The name of the HTML element wrapping the date value.

Default: span

editable

Explicitly enable/disable inline editing. If true and field.editable has a value, then field.editable is processed and rendered as component output. If false, the field.editable value is ignored and not rendered.

Default: false

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.

Usage

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

RequestResponse

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()} />
    
    Note

    The 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

value

Required.

The route field you want to render. It represents a Sitecore File type with the properties src, title, and displayName.

children

A React Node, populating the rendered <a/> tag. The default value is the file.

Important

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:

RequestResponse

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

field

Required.

The field data has two properties:

  • The value property - represents the raw field value from the Sitecore item.

  • The editable property - contains the editable markup rendered when editing is enabled.

editable

A Boolean value you can use to enable or disable the inline editing of the image.

Default: true.

imageParams

An array of ImageSizeParameters that converts into query string parameters added to the image URL.

srcSet

An array of ImageSizeParameters definitions for generating comma-separated strings used as a value for the native image srcset attribute.

mediaUrlPrefix

A custom regular expression that finds the media URL prefix to be replaced by /-/jssmedia or /~/jssmedia.

Important

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:

RequestResponse

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"
    />
    

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

field

Required.

The route field you want to render. It must be a Sitecore General Link field type. The field data has the following properties:

  • The value property - represents the raw field value from the Sitecore item.

  • The editableFirstPart property - contains the first part of the editable markup rendered when editing is enabled.

  • The editableLastPart property- contains the last part of the editable markup rendered when editing is enabled.

editable

Indicates whether to use the editor or Sitecore-formatted HTML output.

Default: true

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.

internalLinkMatcher

A Regex pattern for identifying internal links.

Default: /^\//g

showLinkTextWithChildrenPresent

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.

Usage

To use the Link field helper component, you must import it into your component:

RequestResponse

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:

RequestResponse

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

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

field

Required.

The field you want to render. The field data has two properties:

  • The value property - represents the raw field value from the Sitecore item.

  • The editable property - contains the editable markup rendered when editing is enabled.

tag

The name of the HTML element you want to wrap the text value.

Default: span

editable

Indicates whether to use the editor or Sitecore-formatted HTML output.

Default: true

encode

Enables or disables HTML encoding of the output value. A false value also implies editable: false.

Default: true

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:

RequestResponse

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:

RequestResponse

<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

field

Required.

The field you want to render. The field data has two properties:

  • The value property - represents the raw field value from the Sitecore item.

  • The editable property - contains the editable markup rendered when editing is enabled.

tag

The name of the HTML element you want to wrap the text value.

Default: div

editable

Indicates whether to use the editor or Sitecore-formatted HTML output.

Default: true

Usage

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

RequestResponse

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"
    />
    

Do you have some feedback for us?

If you have suggestions for improving this article,