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

July 12, 2024

By Tyler Holmes

Why Does Sitecore Have Its Own JSS Types?

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.

All Common Sitecore JSS Types

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]:
unknown;
src?: string;}
- -
LinkField Object
{value: LinkFieldValue}
<Link/> General Link
LinkFieldValue Object
{[attributeName: string]:
unknown;
href?: string;
className?: string;
class?: string;
title?: string;
target?: string;
text?: string;
anchor?: string;
querystring?: string;
linktype?: string;}
- -
FileField Object
{value: FileFieldValue;}
<File /> File
FileFieldValue Object
{[propName: string]:
unknown;
src?: string;
title?: string;
displayName?: string;}
- -
Date Object
{value: string}
<DateField /> Date

Differences Between Similar JSS Types

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;
}

How to Use Them With the Sitecore’s JSS Components

Text

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

RichText

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

Image

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

File

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>

Date

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

Final Thoughts on JSS Types

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!



Tyler Holmes

Full Stack Developer

Tyler is an experienced Full Stack Developer who has worked on a plethora of unique projects. He possesses a deep understanding of Technical SEO, C#, and React/Next.js.