Reading time: 12 min read
All Sitecore JSS Types and How to Use Them
If you're new to Sitecore and JSS, use this guide to quickly learn the ins and outs of JSS Types and why we have them
If you're new to Sitecore and JSS, use this guide to quickly learn the ins and outs of JSS Types and why we have them
Start typing to search...
Sitecore has the “ExperienceEditor” and XM Cloud now also has “Sitecore Pages” which both allow people to author (the act of building/constructing a page in Sitecore) custom pages. Sitecore provides the user the ability to edit the text directly inside Sitecore Pages, allowing them to edit all the information directly in the page builder.
Since JSS (Sitecore JavaScript Rendering SDKs) is JavaScript, we don't get the natural typing you get in strongly typed languages like C# (which is used for the older versions of sitecore). That's why we have Typescript and the JSS types.
Since we want to provide the author the ability to edit everything directly, all the Sitecore fields that you can
select from when building out the template return objects. The most standard object that you’ll see is a
simple {value: string}, however some of the more unique types have multiple values. Because of this, we
can use our JSS types to get IntelliSense/Typescript to do all the hard work for us.
| Type | Data Type | JSS Component | Example Sitecore Fields |
|---|---|---|---|
Field<string> |
Object {value: string} |
<Text/> |
Integer, Number, Password, and Single-Line & Multi-Line Text fields |
RichTextField |
Object {value: string} |
<RichText/> |
Rich Text Field |
ImageField |
Object {value: ImageFieldValue} |
<Image/> |
Image |
ImageFieldValue |
Object {[attributeName: string]: |
- | - |
LinkField |
Object {value: LinkFieldValue} |
<Link/> |
General Link |
LinkFieldValue |
Object {[attributeName: string]: |
- | - |
FileField |
Object {value: FileFieldValue;} |
<File /> |
File |
FileFieldValue |
Object {[propName: string]: |
- | - |
Date |
Object {value: string} |
<DateField /> |
Date |
Some JSS types look very similar, but act differently. The biggest example would be a normal
<Text/> field vs a <RichText/> field. A <Text/> field uses
a Field<string> type, this provides a simple string that you would want to display inside a
single tag (ex: <p>). A <RichText/> on the other hand is targeted at putting
multiple content tags inside a larger wrapper (ex: <div>).
Another example would be Field vs FieldValue (ex: LinkField vs
LinkFieldValue). When you are creating your typescript types, you might be confused on which one to
use, Field or FieldValue. Simply put: Field will provide you with the type
for the entire Sitecore object, while FieldValue will only give you the intractable object values.
It's important to not only understand the difference, but also understand when you are passing down only the
FieldValue vs the entire Sitecore object. Here is an example using LinkField, notice how
LinkFieldValue is a child of LinkField.
LinkField
{
value: LinkFieldValue; // Child of LinkField
editableFirstPart?: string;
editableLastPart?: string;
}
LinkFieldValue
{
[attributeName: string]: unknown;
href?: string;
className?: string;
class?: string;
title?: string;
target?: string;
text?: string;
anchor?: string;
querystring?: string;
linktype?: string;
}
Component Properties:
| Name | Required | Default Value | Description |
|---|---|---|---|
field |
Yes | - | The field you want to render. |
tag |
No | span |
Which HTML element you want to wrap text value |
editable |
No | true |
Indicates whether to use the editor or Sitecore-formatted HTML output |
encode |
No | true |
Enables or disables HTML encoding of the output value. A false value also implies editable: false.
|
Example Code:
import { Text } from '@sitecore-jss/sitecore-jss-react';
//Default Text Field
<Text field={props.fields.textValue} />
//Text field with a Tag
<Text field={props.fields.textValue} tag="p" />
//Non-editable text field with a custom tag, CSS classes, and custom attributes
<Text
field={props.fields.textValue}
tag="h2"
editable={false}
encode={false}
className="font-weight-bold"
data-sample="other-attributes-pass-through"
/>
Component Properties:
| Name | Required | Default Value | Description |
|---|---|---|---|
field |
Yes | - | The field you want to render. |
tag |
No | div |
Which HTML element you want to wrap text value |
editable |
No | true |
Indicates whether to use the editor or Sitecore-formatted HTML output |
Example Code:
import { RichText } from '@sitecore-jss/sitecore-jss-react';
//Default Rich Text Field
<RichText field={props.fields.richTextValue} />
//Non-editable text field with a custom tag, CSS classes, and custom attributes
<RichText
field={props.fields.richTextValue}
tag="section"
editable={false}
className="font-weight-bold"
data-sample="other-attributes-pass-through"
/>
Component Properties:
| Name | Required | Default Value | Description |
|---|---|---|---|
field |
Yes | - | The Sitecore General Link you want to render |
editable |
No | true |
Indicates whether to use the editor or Sitecore-formatted HTML output. |
showLinkTextWithChildrenPresent |
No | - | A Boolean expression that enables or disables the display of a link description even when children exist. |
Example Code:
import { Link } from '@sitecore-jss/sitecore-jss-react';
//External links
<Link field={props.fields.externalLink} />
//Internal links, with HTML or other components
<Link field={props.fields.internalLink}>
<em>Lorem</em> ipsum dolor sit amet, consectetur adipiscing elit. Etiam elementum.
</Link>
//Additional properties & attributes.
<Link
field={props.fields.externalLink}
showLinkTextWithChildrenPresent={true}
className="font-weight-bold"
data-otherattributes="pass-through-to-anchor-tag"
/>
Component Properties:
| Name | Required | Default Value | Description |
|---|---|---|---|
field |
Yes | - | The Sitecore route field you want to render |
editable |
No | true |
Enable/disable inline editing |
imageParams |
No | [] |
An array of ImageSizeParameters that converts into query string parameters added to the image URL
|
srcSet |
No | [] |
An array of ImageSizeParameters definitions for generating comma-separated strings |
mediaUrlPrefix |
No | - | A custom regular expression that finds media URL prefix to be replaced by /-/jssmedia or
/~/jssmedia. |
Example Code:
import { Image } from '@sitecore-jss/sitecore-jss-react';
//Simple Image Field
<Image media={props.fields.image} />
//Responsive Image Field
<Image
field={props.fields.image}
srcSet={[{ mw: 300 }, { mw: 100 }]}
sizes="(min-width: 960px) 300px, 100px"
className="img-fluid"
/>
//Server-side Image Resizing
<Image
field={props.fields.image}
editable={false}
imageParams={{ mw: 100, mh: 50 }} //Resized based on these values
height="50"
width="94"
data-sample="other-attributes-pass-through"
/>
Component Properties:
| Name | Required | Default Value | Description |
|---|---|---|---|
value |
Yes | - | The sitecore route field you want to render |
children |
No | itself |
A React Node, populating the rendered </a> tag. |
Example Code:
import { File } from '@sitecore-jss/sitecore-jss-react';
//Simple File Field
<File field={props.fields.file} />
//Open in a new tab
<File field={props.fields.file} target="_blank"/>
//Custom Anchor text Field
<File field={props.fields.file}>
View file
</File>
Component Properties:
| Name | Required | Default Value | Description |
|---|---|---|---|
field |
Yes | - | The sitecore field you want to render |
tag |
No | span |
Which HTML element you want to wrap the date value |
editable |
No | true |
Enable/disable inline editing |
render |
No | - | A function that returns the value to render into the tag value |
Example Code:
import { DateField } from '@sitecore-jss/sitecore-jss-react';
//Date Field
<DateField field={props.fields.date} />
//Datetime Field
<DateField field={props.fields.dateTime} />
//Date formatting
<DateField
field={props.fields.dateTime}
render={(date) => <em>{date.toLocaleString()}</em>}
/>
Hopefully this beginner focused guide on Sitecore JSS Types has helped you better understand when and how to use not only each JSS Type, but also its corresponding component!