All Sitecore JSS Types and How to Use Them

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

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:

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:

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

Link

Component Properties:

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:

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:

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:

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!

---