Sitecore JavaScript Rendering SDK (JSS) for React

Sitecore Headless Development
Sitecore JavaScript Services SDK (JSS)
SDKs for React, Angular, Vue, and React Native
Sitecore JavaScript Rendering SDK (JSS) for React
JSS components for rendering Sitecore fields in React applications

JSS components for rendering Sitecore fields in React applications

Version:

JSS for React provides components that help you render Sitecore fields in your React applications.

The following table shows the correspondence between Sitecore field types and JSS React components:

Sitecore field type	JSS React component
Date	`Date`
File	`File`
Image	`Image`
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	Default
`field`	Required. The field you want to render. Must be a Sitecore Date type.	-
`tag`	The name of the HTML element wrapping the date value.	`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.	`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.	-

Usage

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

import { DateField } from '@sitecore-jss/sitecore-jss-react';

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

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:

<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.

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 use the field, you must import it into your component:

import { File } from '@sitecore-jss/sitecore-jss-react';

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>W

Image

The Image component allows you to render editable, responsive images.

The Image component has the following properties:

Name	Description
`field`	Required. Image field data. It accepts an `ImageFieldValue` or `ImageField` object type.
`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 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:

import { Image } from '@sitecore-jss/sitecore-jss-react';

You can use the Image component to render:

A simple image:
<Image media={props.fields.sample1} />

A responsive image:

<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:

 <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 type.

The Link component has the following properties:

Name	Description	Default
`field`	The route field you want to render. It must be a Sitecore General Link type.	-
`editable`	Indicates whether to use the editor or Sitecore-formatted HTML output. 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.	`true`
`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:

import { Link } from '@sitecore-jss/sitecore-jss-react';

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}>
  <em>HTML</em> or other components can be used within link renderers, for example, links to images.
</Link>

Email links:
<Link field={props.fields.emailLink} />
A content parameters link:
<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"
/>

Note

In the Experience Editor, in editor mode, a link description is always rendered. If the link has any children, they are rendered as siblings to the link description.

Text

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

The Text component has the following properties:

Name	Description	Default
`field`	The field you want to render.	-
`tag`	The name of the HTML element you want to wrap the text value.	`span`
`editable`	Indicates whether to use the editor or Sitecore-formatted HTML output.	`true`
`encode`	Enables or disables HTML encoding of the output value. A false value also implies `editable: false`.	`true`

For Multi-line Text, 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-react';

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

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	Default
`field`	The field you want to render.	-
`tag`	The name of the HTML element you want to wrap the text value.	`div`
`editable`	Indicates whether to use the editor or Sitecore-formatted HTML output.	`true`

Usage

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

import { RichText } from '@sitecore-jss/sitecore-jss-react';

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

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