Ricos Document

Wix Ricos defines its own data structure, the Ricos document. Its a central piece of Ricos technology as the rich content editor and viewer are built around it.

Fundamentally, the object structure is a tree of nodes representing content blocks. It includes basic text container nodes (like paragraphs, headings, lists, and so on), as well as more complex nodes that require Ricos plugins to work. These complex nodes allow for the creation of advanced content blocks (like videos, tables, galleries, and so on).

The Ricos document resembles HTML, with various node types acting like HTML tags and their fields functioning as attributes. The nodes field represents the children of HTML tags. The primary difference, and the reason Ricos does not use HTML as its structure, is that the Ricos document imposes more constraints. This allows it to be more easily manipulated and displayed across different environments.

Quicklinks

• For text use Paragraph, Heading, Blockquote, CodeBlock, Text nodes.
• For lists use BulletedList, OrderedList, CollapsibleList, Table nodes.
• For media use Image, Video, Gallery, Gif, Audio, File nodes.
• For embeds use AppEmbed, Embed, LinkPreview, Html nodes.
• Other nodes: Divider, Button.
• Decorations: Bold, Italic, Underline, Spoiler, Anchor, Mention, Link, Color, FontSize

Playground

You can experiment with with rich content directly using the embedded playground we provide. You can experiment in the following way:

• By editing the Ricos document in the Document section of the playground.
• By editing content in the Editor section. You will see how the Ricos document is updated to reflect any changes made in the Editor section.

For a more comfortable experience you can try viewing examples in the Full playground.

Reference

RicosDocument

Field	Type	Description
nodes Required	Array <RootNode>	A collection of predefined individual data elements, such as PARAGRAPH, HEADING, and so on.
metadata	Metadata	Data about the Ricos document, such as version. This property is applicable only when using the ricos content editor and is auto-generated.
documentStyle	DocumentStyle	Defines styles for nodes. For example, you can define general styling for headerOne, and then override some of the properties separately for a specific header.

Nodes

This section describes all possible nodes in the Ricos Document. Some are unions, such as RootNode.

Here is the list of specific nodes, presented in alphabetical order for quick access: AppEmbedNode, AudioNode, BlockquoteNode, BulletedListNode, ButtonNode, CodeBlockNode, CollapsibleItemNode, CollapsibleItemBodyNode, CollapsibleItemTitleNode, CollapsibleListNode, DividerNode, EmbedNode, FileNode, GalleryNode, GifNode, HeadingNode, HtmlNode, ImageNode, LinkPreviewNode, ListItemNode, OrderedListNode, ParagraphNode, PollNode, TableCellNode, TableNode, TableRowNode, TextNode, VideoNode.

RootNode

Used in: RicosDocument

Represents nodes that can be added to the root level of nodes array.

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
AppEmbedNode	APP_EMBED	Similar to LinkPreviewNode, this node is used to embed external content preview, but from Wix business solutions. You can embed previews from the Wix Bookings, Wix Stores and Wix Events apps.
AudioNode	AUDIO	A multimedia node used to embed and play audio content directly in a webpage. When rendered, it is displayed as the audio player with the specified audio file (can be a platform such as Spotify or Soundloud, and Wix Media). Users can interact with the controls to play, pause, rewind, and adjust the volume of the audio.
BlockquoteNode	BLOCKQUOTE	Used to visually distinguish quoted or cited content from the surrounding text. When rendered, it is displayed as the quoted text with indentation or other styling to visually separate it from the surrounding content.
BulletedListNode	BULLETED_LIST	Presents a group of items in a visually organized manner, where each item is preceded by a bullet point. Bulleted lists are commonly used to present unordered information.
ButtonNode	BUTTON	A node that is used to trigger an action when clicked or activated.
CodeBlockNode	CODE_BLOCK	Used to present programming code snippets, markup, or other text-based content that should be displayed exactly as it appears, without any interpretation or formatting applied by the browser. When rendered, it is displayed as the code block with a monospaced font, preserving indentation, line breaks, and spacing as specified in the code.
CollapsibleListNode	COLLAPSIBLE_LIST	A list of items where each item can be expanded or collapsed to reveal or hide additional content associated with it.
DividerNode	DIVIDER	A visual node that is used to separate content sections in a page. When rendered, it is displayed as a horizontal line between the paragraphs, acting as a divider between them.
EmbedNode	EMBED	Similar to HtmlNode, this node is used to display embedded content when you post a link to that resource, without having to parse the resource directly. It provides a standardized way for web developers to include content such as videos, images, and other multimedia elements from supported providers without needing to handle the complex embedding code themselves. For more information, read oembed.
FileNode	FILE	A digital file stored on a computer that is uploaded and accessed in a page. Files can include various types of content, such as text documents, images, videos, and so on.
GalleryNode	GALLERY	A collection of images displayed together in a visually appealing and organized manner.
GifNode	GIF	GIF images are made up of a series of frames, allowing them to display animations or short video clips without the need for additional plugins or technologies.
HeadingNode	HEADING	Used to denote the heading or title of a section. Headings are hierarchical, with different levels indicating the relative importance of the heading in the content's structure. There are 6 levels of headings, where 1 is the highest level and 6 is the lowest.
HtmlNode	HTML	Incorporates external content, such as interactive maps, or entire web pages.
ImageNode	IMAGE	Displays standalone pictures in a page.
LinkPreviewNode	LINK_PREVIEW	A preview or summary of a webpage. Link previews include elements such as the title of the linked page, a brief description or excerpt of the content, and possibly a thumbnail image or other relevant information.
OrderedListNode	ORDERED_LIST	Presents a group of items in a sequentially numbered or lettered manner. Ordered lists are used to represent information that has a specific order or sequence.
ParagraphNode	PARAGRAPH	Used to structure text content, providing a clear separation between different ideas or sections of text. They are rendered with default styling that typically includes some space above and below the paragraph, making it visually distinct from the surrounding content.
PollNode	POLL	A node that allows users to vote or express their opinions on a particular question, topic, or issue.
TableNode	TABLE	A structural node used to display data in rows and columns.
VideoNode	VIDEO	A multimedia node that is used to embed and play video content directly in a page. When rendered, it is displayed as the video player with the specified video file. Users can interact with the controls to play, pause, rewind, and adjust the volume of the video.

ParagraphNode

Used in: RootNode, BlockquoteNode, ListItemChildNode, TableCellChildNode, CollapsibleTitleChildNode, CollapsibleItemBodyChildNode

Used to structure text content, providing a clear separation between different ideas or sections of text. They are rendered with default styling that typically includes some space above and below the paragraph, making it visually distinct from the surrounding content.

Field	Type	Description
type Required	"PARAGRAPH"	Node type. Value: PARAGRAPH
nodes	Array <TextNode>	Paragraph children.
id	string format NODE_ID	Node ID.
style	NodeStyle	Paragraphs vertical padding. Note: This node requires the lineSpacing plugin for styling.
paragraphData	ParagraphData	Paragraph node attributes.

ParagraphData

Used in: ParagraphNode

Field	Type	Description
textStyle	TextStyle	Styling for the paragraph text.
indentation	int32	Paragraph margin from the left side. Possible values are from 1 to 4. Actual indentation is equal to indentation * 40px.

TextNode

Used in: ParagraphNode, HeadingNode, CodeBlockNode

Text nodes hold the text itself (think span tag in HTML). The difference between TextNode and HTML span is that text nodes can't be nested and must contain non-empty string. Their appearance and behavior can be modified using decorations.

Field	Type	Description
type Required	"TEXT"	Node type. Value: TEXT
textData Required	TextData	Text options.
id	string format NODE_ID	Node ID.

TextData

Used in: TextNode

Field	Type	Description
text Required	string minLength: 1	A piece of text, possibly enhanced with additional decorations. Must not be empty.
decorations	Array <Decoration> Unique Tags	Text decoration options, such as font and text color. Each type of decoration must appear at most once in this array.

HeadingNode

Used in: RootNode, ListItemChildNode, TableCellChildNode, CollapsibleTitleChildNode, CollapsibleItemBodyChildNode

Used to denote the heading or title of a section. Headings are hierarchical, with different levels indicating the relative importance of the heading in the content's structure. There are 6 levels of headings, where 1 is the highest level and 6 is the lowest.

Field	Type	Description
type Required	"HEADING"	Node type. Value: HEADING
nodes	Array <TextNode>	Child nodes to define the heading text.
id	string format NODE_ID	Node ID.
style	NodeStyle	Defines the heading style, such as padding and background color. Note: This node requires the lineSpacing plugin for styling.
headingData	HeadingData	Heading options.

HeadingData

Used in: HeadingNode

Field	Type	Description
level	int32	Heading size from 1 to 6, where 1 is the highest level and 6 is the lowest.
textStyle	TextStyle	Defines the heading text style, such as text alignment and line height.
indentation	int32	Heading margin from the left side. Possible values are from 1 to 4. The indentation is measured in relative to the font size em units, by the following formula: indentation * 1.5. For example, if indentation is 2, then margin is equal to 3em. Therefore the margin is 3 times the size of the font.

ImageNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

Displays standalone pictures in a page.

Field	Type	Description
type Required	"IMAGE"	Node type. Value: IMAGE
imageData Required	ImageData	Image options.
id	string format NODE_ID	Node ID.

ImageData

Used in: ImageNode

Field	Type	Description
image Required	Media	Image file details, such as source and dimensions.
containerData	PluginContainerData	Styling for the image container, such as dimensions and alignment.
link	Link	Link details, such as URL, or anchor, if image is also used as a link.
disableExpand	boolean	Whether the image expands to the full screen when clicked. Default: false
altText	string	An alternate text for an image. Used for improved accessibility and shown when the image can't be displayed.
caption	string	Image title.
disableDownload	boolean	Whether the download image button is disabled. Default: false

OrderedListNode

Used in: RootNode, ListItemChildNode, TableCellChildNode, CollapsibleItemBodyChildNode

Presents a group of items in a sequentially numbered or lettered manner. Ordered lists are used to represent information that has a specific order or sequence.

Field	Type	Description
type Required	"ORDERED_LIST"	Node type. Value: ORDERED_LIST
nodes Required	Array <ListItemNode> minItems: 1	List items.
id	string format NODE_ID	Node ID.
orderedListData	OrderedListData	Ordered list details.

OrderedListData

Used in: OrderedListNode

Field	Type	Description
indentation Deprecated	int32	List margin from the left side. Possible values are from 1 to 4. The indentation is measured in relative to the font size em units, by the following formula: indentation * 1.5. For example, if indentation is 2, then margin is equal to 3em. Therefore the margin is 3 times the size of the font.
offset	int32	An integer (ranging from 0 to 4) used to control the additional indentation level of an ordered or bulleted list node, beyond its original HTML-defined nesting. When offset is 0, the list node appears at its default nesting level; as the value increases from 1 to 4, the node is indented further, creating the visual impression of deeper nesting without altering the actual HTML structure.

BulletedListNode

Used in: RootNode, ListItemChildNode, TableCellChildNode, CollapsibleItemBodyChildNode

Presents a group of items in a visually organized manner, where each item is preceded by a bullet point. Bulleted lists are commonly used to present unordered information.

Field	Type	Description
type Required	"BULLETED_LIST"	Node type. Value: BULLETED_LIST
nodes Required	Array <ListItemNode> minItems: 1	List items.
id	string format NODE_ID	Node ID.
bulletedListData	BulletedListData	Bulleted list details.

BulletedListData

Used in: BulletedListNode

Field	Type	Description
indentation Deprecated	int32
offset	int32	An integer (ranging from 0 to 4) used to control the additional indentation level of an ordered or bulleted list node, beyond its original HTML-defined nesting. When offset is 0, the list node appears at its default nesting level; as the value increases from 1 to 4, the node is indented further, creating the visual impression of deeper nesting without altering the actual HTML structure.

ListItemNode

Used in: BulletedListNode, OrderedListNode

Field	Type	Description
type Required	"LIST_ITEM"	Node type. Value: LIST_ITEM
nodes Required	Array <ListItemChildNode>	Child nodes that the list item contains. Array items must adhere to the pattern described above this table.
id	string format NODE_ID	Node ID.

ListItemChildNode

Used in: ListItemNode

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
BulletedListNode	BULLETED_LIST	Presents a group of items in a visually organized manner, where each item is preceded by a bullet point. Bulleted lists are commonly used to present unordered information.
HeadingNode	HEADING	Used to denote the heading or title of a section. Headings are hierarchical, with different levels indicating the relative importance of the heading in the content's structure. There are 6 levels of headings, where 1 is the highest level and 6 is the lowest.
OrderedListNode	ORDERED_LIST	Presents a group of items in a sequentially numbered or lettered manner. Ordered lists are used to represent information that has a specific order or sequence.
ParagraphNode	PARAGRAPH	Used to structure text content, providing a clear separation between different ideas or sections of text. They are rendered with default styling that typically includes some space above and below the paragraph, making it visually distinct from the surrounding content.

BlockquoteNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

Used to visually distinguish quoted or cited content from the surrounding text. When rendered, it is displayed as the quoted text with indentation or other styling to visually separate it from the surrounding content.

Field	Type	Description
type Required	"BLOCKQUOTE"	Node type. Value: BLOCKQUOTE
nodes Required	Array <ParagraphNode> minItems: 1 maxItems: 1	Child nodes to define a blockquote paragraph.
id	string format NODE_ID	Node ID.
blockquoteData	BlockquoteData	Blockquote details.
style	NodeStyle	Defines the blockquote style, such as padding and background color. Note: This node requires the lineSpacing plugin for styling.

BlockquoteData

Used in: BlockquoteNode

Field	Type	Description
indentation	int32	Blockquote margin from the left side. Possible values are from 1 to 4. The indentation is measured in relative to the font size em units, by the following formula: indentation * 1.5. For example, if indentation is 2, then margin is equal to 3em. Therefore the margin is 3 times the size of the font.

GifNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

GIF images are made up of a series of frames, allowing them to display animations or short video clips without the need for additional plugins or technologies.

Field	Type	Description
type Required	"GIF"	Node type. Value: GIF
gifData Required	GIFData	GIF details.
id	string format NODE_ID	Node ID.

GIFData

Used in: GifNode

Field	Type	Description
containerData	PluginContainerData	Styling for the GIF container, such as dimensions and alignment.
original	GIF	Source for the full size GIF.
downsized	GIF	Source for the downsized GIF.
height	int32	Height in pixels.
width	int32	Width in pixels.

GIF

Used in: GIFData

Field	Type	Description
gif	string format WEB_URL	URL for a file in GIF format.
mp4	string format WEB_URL	URL for a file in MP4 format.
still	string format WEB_URL	GIF thumbnail URL.

VideoNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

A multimedia node that is used to embed and play video content directly in a page. When rendered, it is displayed as the video player with the specified video file. Users can interact with the controls to play, pause, rewind, and adjust the volume of the video.

Field	Type	Description
type Required	"VIDEO"	Node type. Value: VIDEO
videoData Required	VideoData	Video details.
id	string format NODE_ID	Node ID.

VideoData

Used in: VideoNode

Field	Type	Description
video Required	Media	Video file details, such as source and dimensions.
containerData	PluginContainerData	Styling for the video container, such as dimensions and alignment.
thumbnail	Media	Video thumbnail details, such as dimensions.
disableDownload	boolean	Whether the video download button is disabled. Default: false
title	string	Video title.
options	PlaybackOptions	Playback details.

PlaybackOptions

Used in: VideoData

Field	Type	Description
autoPlay	boolean	Whether the media automatically starts playing after opening a page.
playInLoop	boolean	Whether the media is looped.
showControls	boolean	Whether to show the media controls.

TableNode

Used in: RootNode

A structural node used to display data in rows and columns.

Field	Type	Description
type Required	"TABLE"	Node type. Value: TABLE
nodes Required	Array <TableRowNode> minItems: 1	Child nodes to define table rows.
id	string format NODE_ID	Node ID.
tableData	TableData	Table details.

TableRowNode

Used in: TableNode

Field	Type	Description
type Required	"TABLE_ROW"	Node type. Value: TABLE_ROW
nodes Required	Array <TableCellNode> minItems: 1	Child nodes to define table cells.
id	string format NODE_ID	Node ID.

TableData

Used in: TableNode

Field	Type	Description
containerData	PluginContainerData	Styling for the table container, such as dimensions and alignment.
dimensions	TableData_Dimensions	Table dimensions.
rowHeader	boolean	Whether the table's first row is a heading. Default: false
columnHeader	boolean	Whether the table's first column is a heading. Default: false

TableData_Dimensions

Used in: TableData

Field	Type	Description
colsWidthRatio	Array <float64 >	Each column width as related to the width of table.
rowsHeight	Array <uint32 >	Height of each row.
colsMinWidth	Array <uint32 >	Minimum width of each column.

TableCellNode

Used in: TableRowNode

Field	Type	Description
type Required	"TABLE_CELL"	Node type. Value: TABLE_CELL
nodes Required	Array <TableCellChildNode> minItems: 1	Child nodes to define cell content.
id	string format NODE_ID	Node ID.
tableCellData	TableCellData	Table cell details.

TableCellChildNode

Used in: TableCellNode

Table cell content node.

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
AudioNode	AUDIO	A multimedia node used to embed and play audio content directly in a webpage. When rendered, it is displayed as the audio player with the specified audio file (can be a platform such as Spotify or Soundloud, and Wix Media). Users can interact with the controls to play, pause, rewind, and adjust the volume of the audio.
BlockquoteNode	BLOCKQUOTE	Used to visually distinguish quoted or cited content from the surrounding text. When rendered, it is displayed as the quoted text with indentation or other styling to visually separate it from the surrounding content.
BulletedListNode	BULLETED_LIST	Presents a group of items in a visually organized manner, where each item is preceded by a bullet point. Bulleted lists are commonly used to present unordered information.
CodeBlockNode	CODE_BLOCK	Used to present programming code snippets, markup, or other text-based content that should be displayed exactly as it appears, without any interpretation or formatting applied by the browser. When rendered, it is displayed as the code block with a monospaced font, preserving indentation, line breaks, and spacing as specified in the code.
DividerNode	DIVIDER	A visual node that is used to separate content sections in a page. When rendered, it is displayed as a horizontal line between the paragraphs, acting as a divider between them.
FileNode	FILE	A digital file stored on a computer that is uploaded and accessed in a page. Files can include various types of content, such as text documents, images, videos, and so on.
GifNode	GIF	GIF images are made up of a series of frames, allowing them to display animations or short video clips without the need for additional plugins or technologies.
HeadingNode	HEADING	Used to denote the heading or title of a section. Headings are hierarchical, with different levels indicating the relative importance of the heading in the content's structure. There are 6 levels of headings, where 1 is the highest level and 6 is the lowest.
ImageNode	IMAGE	Displays standalone pictures in a page.
OrderedListNode	ORDERED_LIST	Presents a group of items in a sequentially numbered or lettered manner. Ordered lists are used to represent information that has a specific order or sequence.
ParagraphNode	PARAGRAPH	Used to structure text content, providing a clear separation between different ideas or sections of text. They are rendered with default styling that typically includes some space above and below the paragraph, making it visually distinct from the surrounding content.
VideoNode	VIDEO	A multimedia node that is used to embed and play video content directly in a page. When rendered, it is displayed as the video player with the specified video file. Users can interact with the controls to play, pause, rewind, and adjust the volume of the video.

TableCellData

Used in: TableCellNode

Field	Type	Description
cellStyle	TableCellData_CellStyle	Styling for the cell, such as background color and text alignment.
borderColors	TableCellData_BorderColors	Cell border colors.

TableCellData_CellStyle

Used in: TableCellData

Field	Type	Description
verticalAlignment	enum: "TOP", "MIDDLE", "BOTTOM"	Vertical alignment for the cell's text. Possible values: - TOP: Aligns the top padding edge of the cell with the top of the row. - MIDDLE: Centers the padding box of the cell in the row. - BOTTOM: Aligns the bottom padding edge of the cell with the bottom of the row.
backgroundColor	string format COLOR_HEX	Cell background color in a hexadecimal value, for example #4287f5.

TableCellData_BorderColors

Used in: TableCellData

Field	Type	Description
left	string format COLOR_HEX	Left border color in a hexadecimal value.
right	string format COLOR_HEX	Right border color in a hexadecimal value.
top	string format COLOR_HEX	Top border color in a hexadecimal value.
bottom	string format COLOR_HEX	Bottom border color in a hexadecimal value.

AppEmbedNode

Used in: RootNode, CollapsibleItemBodyChildNode

Similar to LinkPreviewNode, this node is used to embed external content preview, but from Wix business solutions. You can embed previews from the Wix Bookings, Wix Stores and Wix Events apps.

Field	Type	Description
type Required	"APP_EMBED"	Node type. Value: APP_EMBED
id	string format NODE_ID	Node ID.
appEmbedData	AppEmbedData	Embedded Wix app details.

AppEmbedData

Used in: AppEmbedNode

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
AppEmbedDataBooking	BOOKING	Wix Bookings app. Embeds a particular booking.
AppEmbedDataEvent	EVENT	Wix Events app. Embeds a particular event.
AppEmbedDataProduct	PRODUCT	Wix Stores app. Embeds a particular product.

AppEmbedDataProduct

Used in: AppEmbedData

Wix Stores app. Embeds a particular product.

Field	Type	Description
type Required	"PRODUCT"	Which Wix App to embed. Possible values: - PRODUCT: Wix Stores app. Embeds a particular product. - EVENT: Wix Events app. Embeds a particular event. - BOOKINGS: Wix Bookings app. Embeds a particular booking.
name Required	string	Embedded content name.
image Required	Media	Embedded content thumbnail.
itemId	string	Embedded content ID.
url	string	Embedded content URL.
imageSrc Deprecated	string	Deprecated: Use image instead.

AppEmbedDataEvent

Used in: AppEmbedData

Wix Events app. Embeds a particular event.

Field	Type	Description
type Required	"EVENT"
name Required	string	Embedded content name.
image Required	Media	Embedded content thumbnail.
eventData Required	AppEmbedData_EventData	Embedded Wix Events app content.
itemId	string	Embedded content ID.
url	string	Embedded content URL.
imageSrc Deprecated	string	Deprecated: Use image instead.

AppEmbedDataBooking

Used in: AppEmbedData

Wix Bookings app. Embeds a particular booking.

Field	Type	Description
type Required	"BOOKING"
name Required	string	Embedded content name.
image Required	Media	Embedded content thumbnail.
itemId	string	Embedded content ID.
url	string	Embedded content URL.
bookingData	AppEmbedData_BookingData	Embedded Wix Bookings app content.
imageSrc Deprecated	string	Deprecated: Use image instead.

AppEmbedData_BookingData

Used in: AppEmbedDataBooking

Field	Type	Description
durations	string	Booking duration in minutes.

AppEmbedData_EventData

Used in: AppEmbedDataEvent

Field	Type	Description
scheduling	string	Event schedule.
location	string	Event location.

EmbedNode

Used in: RootNode

Similar to HtmlNode, this node is used to display embedded content when you post a link to that resource, without having to parse the resource directly. It provides a standardized way for web developers to include content such as videos, images, and other multimedia elements from supported providers without needing to handle the complex embedding code themselves. For more information, read oembed.

Field	Type	Description
type Required	"EMBED"	Node type. Value: EMBED
embedData Required	EmbedData	oEmbed details.
id	string format NODE_ID	Node ID.

EmbedData

Used in: EmbedNode

Field	Type	Description
containerData	PluginContainerData	oEmbed node container styling.
oembed	Oembed	oEmbed details.
src	string	Original asset source.

Oembed

Used in: EmbedData

Field	Type	Description
type	string	Resource type. For more information read the oEmbed official website.
width	int32	Width of the resource specified in the url field in pixels.
height	int32	Height of the resource specified in the url field in pixels.
title	string	A text title, describing the resource.
url	string	The source URL for the resource.
html	string	HTML required to embed a video player. The HTML should have no padding or margins.
authorName	string	Name of the author or owner of the resource.
authorUrl	string	URL for the author or owner of the resource.
providerName	string	Name of the resource provider.
providerUrl	string	URL for the resource provider.
thumbnailUrl	string	URL for a thumbnail image for the resource. If this property is defined, thumbnailWidth and thumbnailHeight must also be defined.
thumbnailWidth	string	Width of the resource's thumbnail image. If this property is defined, thumbnailUrl and thumbnailHeight must also be defined.
thumbnailHeight	string	Height of the resource's thumbnail image. If this property is defined, thumbnailUrl and thumbnailWidthmust also be defined.
videoUrl	string	URL for an embedded video.
version	string	The oEmbed version number. This value must be 1.0.

DividerNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

A visual node that is used to separate content sections in a page. When rendered, it is displayed as a horizontal line between the paragraphs, acting as a divider between them.

Field	Type	Description
type Required	"DIVIDER"	Node type. Value: DIVIDER
id	string format NODE_ID	Node ID.
dividerData	DividerData	Divider details.

DividerData

Used in: DividerNode

Field	Type	Description
containerData	PluginContainerData	Divider container styling.
lineStyle	enum: "SINGLE", "DOUBLE", "DASHED", "DOTTED"	Divider line style. Possible values: - SINGLE - DOUBLE - DASHED - DOTTED
width	enum: "LARGE", "MEDIUM", "SMALL"	Divider width. Possible values: - LARGE - MEDIUM - SMALL
alignment	enum: "CENTER", "LEFT", "RIGHT"	Divider alignment. Possible values: - CENTER - LEFT - RIGHT

CodeBlockNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

Used to present programming code snippets, markup, or other text-based content that should be displayed exactly as it appears, without any interpretation or formatting applied by the browser. When rendered, it is displayed as the code block with a monospaced font, preserving indentation, line breaks, and spacing as specified in the code.

Field	Type	Description
type Required	"CODE_BLOCK"	Node type. Value: CODE_BLOCK
nodes	Array <TextNode>	Child nodes to define a code block text.
id	string format NODE_ID	Node ID.
codeBlockData	CodeBlockData	Code block details.
style	NodeStyle	Defines the blockquote style, such as padding and background color. Note: This node requires the lineSpacing plugin for styling.

CodeBlockData

Used in: CodeBlockNode

Field	Type	Description
textStyle	TextStyle	Defines the text style, such as alignment and line height.

LinkPreviewNode

Used in: RootNode, CollapsibleItemBodyChildNode

A preview or summary of a webpage. Link previews include elements such as the title of the linked page, a brief description or excerpt of the content, and possibly a thumbnail image or other relevant information.

Field	Type	Description
type Required	"LINK_PREVIEW"	Node type. Value: LINK_PREVIEW
linkPreviewData Required	LinkPreviewData	Link preview details.
id	string format NODE_ID	Node ID.

LinkPreviewData

Used in: LinkPreviewNode

Field	Type	Description
containerData	PluginContainerData	Link preview container styling.
link	Link	Link details.
title	string	Preview title.
thumbnailUrl	string	Preview thumbnail URL.
description	string	Preview description.
html	string	Preview content as HTML.

AudioNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

A multimedia node used to embed and play audio content directly in a webpage. When rendered, it is displayed as the audio player with the specified audio file (can be a platform such as Spotify or Soundloud, and Wix Media). Users can interact with the controls to play, pause, rewind, and adjust the volume of the audio.

Field	Type	Description
type Required	"AUDIO"	Node type. Value: AUDIO
id	string format NODE_ID	Node ID.
audioData	AudioData	Audio details.

AudioData

Used in: AudioNode

Field	Type	Description
containerData	PluginContainerData	Audio node container styling.
audio	Media	Audio file details.
disableDownload	boolean	Sets whether the audio download button is disabled. Default: false
coverImage	Media	Cover image.
name	string	Track name.
authorName	string	Author name.
html	string	An HTML version of the audio node.

GalleryNode

Used in: RootNode

A collection of images displayed together in a visually appealing and organized manner.

Field	Type	Description
type Required	"GALLERY"	Node type. Value: GALLERY
galleryData Required	GalleryData	Gallery node details.
id	string format NODE_ID	Node ID.

GalleryData

Used in: GalleryNode

Field	Type	Description
items Required	Array <GalleryData_Item> minItems: 1	Gallery items details.
containerData	PluginContainerData	Gallery container styling.
options	GalleryOptions	Gallery appearance options.
disableExpand	boolean	Whether the expand button is disabled. Default: false
disableDownload	boolean	Whether the download button is disabled. Default: false

GalleryOptions

Used in: GalleryData

Field	Type	Description
layout	GalleryOptions_Layout	Gallery layout.
item	GalleryOptions_ItemStyle	Styling for gallery items.
thumbnails	GalleryOptions_Thumbnails	Styling for gallery thumbnail images.

GalleryOptions_Layout

Used in: GalleryOptions

Field	Type	Description
type	enum: "COLLAGE", "MASONRY", "GRID", "THUMBNAIL", "SLIDER", "SLIDESHOW", "PANORAMA", "COLUMN", "MAGIC", "FULLSIZE"	Gallery layout type. Possible values: - COLLAGE: Presents images in various sizes and positions, creating an artistic or dynamic layout. - MASONRY: A grid-based design that places items in optimal positions based on available vertical space, creating an arrangement where items of varying heights fit together like bricks in a wall. - GRID: A layout structure that organizes items into rows and columns, creating a clean, uniform, and visually appealing arrangement of images. - THUMBNAIL: A smaller, scaled-down version of an image that serves as a preview. - SLIDER: A component that allows users to browse through a set of images by sliding or swiping through them, typically in a confined viewing area. - SLIDESHOW: A component that automatically or manually transitions through a set of images in a designated area. - PANORAMA: Wide-angle or 360-degree image that allows users to view an extended horizontal view of a scene. - COLUMN: Arrangement of the gallery items in vertical sections. - MAGIC: Visually stunning, dynamic effects that enhance the user experience. - FULLSIZE: A layout where each image or item is displayed at its full size, taking up the entire viewport or a significant portion of the screen..
horizontalScroll	boolean	Whether the horizontal scroll is enabled. Default: true, unless the type field is set to GRID or COLLAGE.
orientation	enum: "ROWS", "COLUMNS"	Gallery orientation. Possible values: - ROWS: Gallery items are arranged horizontally in rows. - COLUMNS: Gallery items are arranged vertically in columns.
numberOfColumns	int32	The number of columns to display on computer screens.
mobileNumberOfColumns	int32	The number of columns to display on mobile phone screens.

GalleryOptions_ItemStyle

Used in: GalleryOptions

Field	Type	Description
targetSize	int32	Dimension for each gallery item in pixels (behavaior changes according to a gallery type).
ratio	float64	Item ratio
crop	enum: "FILL", "FIT"	Sets how gallery item images are cropped. Possible values: - FILL: Each item in the gallery is cropped and resized to completely fill its container, ensuring that no empty space is left while maintaining the aspect ratio of the original image. - FIT: Each item in the gallery is resized to fit entirely in its container without any cropping.
spacing	int32	The spacing between gallery items in pixels.

GalleryOptions_Thumbnails

Used in: GalleryOptions

Field	Type	Description
placement	enum: "TOP", "RIGHT", "BOTTOM", "LEFT", "NONE"	Thumbnail alignment. Possible values: - TOP - RIGHT - BOTTOM - LEFT - NONE
spacing	int32	Spacing between thumbnails in pixels.

GalleryData_Item

Used in: GalleryData

Field	Type	Description
title	string	Item title.
altText	string	Item's alternative text.
image Required One Of	GalleryData_Item_Image	Image item.
video Required One Of	GalleryData_Item_Video	Video item.

GalleryData_Item_Video

Used in: GalleryData_Item

Field	Type	Description
media Required	Media	Video file details.
thumbnail	Media	Video thumbnail file details.

GalleryData_Item_Image

Used in: GalleryData_Item

Field	Type	Description
media Required	Media	Image file details.
link	Link	Link details for images that are links.

CollapsibleListNode

Used in: RootNode

A list of items where each item can be expanded or collapsed to reveal or hide additional content associated with it.

Field	Type	Description
type Required	"COLLAPSIBLE_LIST"	Node type. Value: COLLAPSIBLE_LIST
nodes Required	Array <CollapsibleItemNode> minItems: 1	Collapsible list child nodes.
id	string format NODE_ID	Node ID.
collapsibleListData	CollapsibleListData	Collapsible list details.

CollapsibleListData

Used in: CollapsibleListNode

Field	Type	Description
containerData	PluginContainerData	Collapsible list container styling.
expandOnlyOne	boolean	Whether only one item can be expanded at a time. Default: false
initialExpandedItems	enum: "FIRST", "ALL", "NONE"	Sets which items are automatically expanded after the page loads. Possible values: - FIRST - ALL - NONE
direction	enum: "LTR", "RTL"	Direction of the text in the list. Possible values: - LTR: Left to right. - RTL: Right to left.
isQapageData	boolean	Whether the collapsible item will appear in search results as a FAQ.

CollapsibleItemNode

Used in: CollapsibleListNode

Field	Type	Description
type Required	"COLLAPSIBLE_ITEM"	Node type. Value: COLLAPSIBLE_ITEM
nodes Required	Array <CollapsibleItemChildNode>	Collapsible list item. Array items must adhere to the pattern described above this table.
id	string format NODE_ID	Node ID.

CollapsibleItemChildNode

Used in: CollapsibleItemNode

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
CollapsibleItemBodyNode	COLLAPSIBLE_ITEM_BODY	Collapsible list item body node.
CollapsibleItemTitleNode	COLLAPSIBLE_ITEM_TITLE	Collapsible list item title node.

CollapsibleItemTitleNode

Used in: CollapsibleItemChildNode

Collapsible list item title node.

Field	Type	Description
type Required	"COLLAPSIBLE_ITEM_TITLE"	Node type. Value: COLLAPSIBLE_ITEM_TITLE
nodes Required	Array <CollapsibleTitleChildNode> minItems: 1 maxItems: 1	Collapsible list item title child nodes.
id	string format NODE_ID	Node ID.

CollapsibleTitleChildNode

Used in: CollapsibleItemTitleNode

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
HeadingNode	HEADING	Used to denote the heading or title of a section. Headings are hierarchical, with different levels indicating the relative importance of the heading in the content's structure. There are 6 levels of headings, where 1 is the highest level and 6 is the lowest.
ParagraphNode	PARAGRAPH	Used to structure text content, providing a clear separation between different ideas or sections of text. They are rendered with default styling that typically includes some space above and below the paragraph, making it visually distinct from the surrounding content.

CollapsibleItemBodyNode

Used in: CollapsibleItemChildNode

Collapsible list item body node.

Field	Type	Description
type Required	"COLLAPSIBLE_ITEM_BODY"	Node type. Value: COLLAPSIBLE_ITEM_BODY
nodes Required	Array <CollapsibleItemBodyChildNode> minItems: 1	Collapsible list item body child nodes.
id	string format NODE_ID	Node ID.

CollapsibleItemBodyChildNode

Used in: CollapsibleItemBodyNode

Collapsible list item body node.

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
AppEmbedNode	APP_EMBED	Similar to LinkPreviewNode, this node is used to embed external content preview, but from Wix business solutions. You can embed previews from the Wix Bookings, Wix Stores and Wix Events apps.
AudioNode	AUDIO	A multimedia node used to embed and play audio content directly in a webpage. When rendered, it is displayed as the audio player with the specified audio file (can be a platform such as Spotify or Soundloud, and Wix Media). Users can interact with the controls to play, pause, rewind, and adjust the volume of the audio.
BlockquoteNode	BLOCKQUOTE	Used to visually distinguish quoted or cited content from the surrounding text. When rendered, it is displayed as the quoted text with indentation or other styling to visually separate it from the surrounding content.
BulletedListNode	BULLETED_LIST	Presents a group of items in a visually organized manner, where each item is preceded by a bullet point. Bulleted lists are commonly used to present unordered information.
CodeBlockNode	CODE_BLOCK	Used to present programming code snippets, markup, or other text-based content that should be displayed exactly as it appears, without any interpretation or formatting applied by the browser. When rendered, it is displayed as the code block with a monospaced font, preserving indentation, line breaks, and spacing as specified in the code.
DividerNode	DIVIDER	A visual node that is used to separate content sections in a page. When rendered, it is displayed as a horizontal line between the paragraphs, acting as a divider between them.
FileNode	FILE	A digital file stored on a computer that is uploaded and accessed in a page. Files can include various types of content, such as text documents, images, videos, and so on.
GifNode	GIF	GIF images are made up of a series of frames, allowing them to display animations or short video clips without the need for additional plugins or technologies.
HeadingNode	HEADING	Used to denote the heading or title of a section. Headings are hierarchical, with different levels indicating the relative importance of the heading in the content's structure. There are 6 levels of headings, where 1 is the highest level and 6 is the lowest.
ImageNode	IMAGE	Displays standalone pictures in a page.
LinkPreviewNode	LINK_PREVIEW	A preview or summary of a webpage. Link previews include elements such as the title of the linked page, a brief description or excerpt of the content, and possibly a thumbnail image or other relevant information.
OrderedListNode	ORDERED_LIST	Presents a group of items in a sequentially numbered or lettered manner. Ordered lists are used to represent information that has a specific order or sequence.
ParagraphNode	PARAGRAPH	Used to structure text content, providing a clear separation between different ideas or sections of text. They are rendered with default styling that typically includes some space above and below the paragraph, making it visually distinct from the surrounding content.
VideoNode	VIDEO	A multimedia node that is used to embed and play video content directly in a page. When rendered, it is displayed as the video player with the specified video file. Users can interact with the controls to play, pause, rewind, and adjust the volume of the video.

FileNode

Used in: RootNode, TableCellChildNode, CollapsibleItemBodyChildNode

A digital file stored on a computer that is uploaded and accessed in a page. Files can include various types of content, such as text documents, images, videos, and so on.

Field	Type	Description
type Required	"FILE"	Node type. Value: FILE
fileData Required	FileData	File details.
id	string format NODE_ID	Node ID.

FileData

Used in: FileNode

Field	Type	Description
containerData	PluginContainerData	File container styling.
src	FileSource	File data source.
name	string	File name.
type	string	File type.
size Deprecated	uint32	Deprecated. Replaced by sizeInKb
sizeInKb	string	File size in KB.
pdfSettings	FileData_PDFSettings	Settings for PDF files.
mimeType	string	File MIME type.
path	string	File path.

FileData_PDFSettings

Used in: FileData

Field	Type	Description
viewMode	enum: "NONE", "FULL", "MINI"	PDF view mode. Possible values: - NONE: The PDF isn't displayed. - FULL: A full PDF page view is displayed. - MINI: A mini view of the PDF is displayed.
disableDownload	boolean	Whether the PDF download button is disabled. Default: false
disablePrint	boolean	Whether the PDF print button is disabled. Default: false

ButtonNode

Used in: RootNode

A node that is used to trigger an action when clicked or activated.

Field	Type	Description
type Required	"BUTTON"	Node type. Value: BUTTON
buttonData Required	ButtonData	Button details.
id	string format NODE_ID	Node ID.

ButtonData

Used in: ButtonNode

Field	Type	Description
type Required	enum: "LINK", "ACTION"	Button type. Possible values: - LINK: When clicked, a user is redirected. - ACTION: When clicked, performs an action.
text Required	string	Button text.
containerData	PluginContainerData	Button container styling.
styles	ButtonData_Styles	Button styling.
link	Link	Button link details.

ButtonData_Styles

Used in: ButtonData

Field	Type	Description
border	ButtonData_Styles_Border	Border properties.
colors	ButtonData_Styles_Colors	Color properties.

ButtonData_Styles_Colors

Used in: ButtonData_Styles

Field	Type	Description
text	string	The text color in a hexadecimal value.
border	string	The border color in a hexadecimal value.
background	string	The background color in a hexadecimal value.

ButtonData_Styles_Border

Used in: ButtonData_Styles

Field	Type	Description
width	int32	Border width in pixels.
radius	int32	Border radius in pixels.

PollNode

Used in: RootNode

A node that allows users to vote or express their opinions on a particular question, topic, or issue.

Field	Type	Description
type Required	"POLL"	Node type. Value: POLL
pollData Required	PollData	Poll details.
id	string format NODE_ID	Node ID.

PollData

Used in: PollNode

Field	Type	Description
containerData	PluginContainerData	Poll container styling.
poll	PollData_Poll	Poll data.
layout	PollData_Layout	Poll layout settings.
design	PollData_Design	Poll design.

PollData_Poll

Used in: PollData

Field	Type	Description
id	string format NODE_ID	Node ID.
title	string	Poll title.
creatorId	string	Poll creator ID.
image	Media	Main poll image.
options	Array <PollData_Poll_Option>	Poll details.
settings	PollData_Poll_Settings	Poll display settings.

PollData_Poll_Option

Used in: PollData_Poll

Field	Type	Description
id	string	Poll option ID.
title	string	Poll option title
image	Media	Image displayed with the option.

PollData_Poll_Settings

Used in: PollData_Poll

Field	Type	Description
permissions	PollData_Poll_Settings_Permissions	Permission settings for voting.
showVoters	boolean	Whether to display the voters in the vote results. Default: true.
showVotesCount	boolean	Whether to display the vote count. Default: true.

PollData_Poll_Settings_Permissions

Used in: PollData_Poll_Settings

Field	Type	Description
view	enum: "CREATOR", "VOTERS", "EVERYONE"	Who can view the poll results. Possible values: - CREATOR: Only poll creator can see the results. - VOTERS: Only voters can see the results. - EVERYONE: Anyone who visits the site can see the results.
vote	enum: "SITE_MEMBERS", "ALL"	Who can vote. Possble values: - SITE_MEMBERS: Only site members can vote. - ALL: All site visitors can vote.
allowMultipleVotes	boolean	Whether one site visitor can vote multiple times. Default: false

PollData_Layout

Used in: PollData

Field	Type	Description
poll	PollData_Layout_PollLayout	Poll layout settings.
options	PollData_Layout_OptionLayout	Poll options layout settings.

PollData_Layout_PollLayout

Used in: PollData_Layout

Field	Type	Description
type	enum: "LIST", "GRID"	Voting options layout. Possible values: - LIST: Options are displayed as a list. - GRID: Options are displayed in a grid..
direction	enum: "LTR", "RTL"	Direction of the text in the poll. Possible values: - LTR: Left to right. - RTL: Right to left.
enableImage	boolean	Whether to display the main poll image. Default: false

PollData_Layout_OptionLayout

Used in: PollData_Layout

Field	Type	Description
enableImage	boolean	Whether to display option images. Defaults: false.

PollData_Design

Used in: PollData

Field	Type	Description
poll	PollData_Design_PollDesign	Poll styling.
options	PollData_Design_OptionDesign	Voting options styling.

PollData_Design_PollDesign

Used in: PollData_Design

Field	Type	Description
background	PollData_Design_PollDesign_Background	Poll background styling.
borderRadius	int32	Border radius in pixels.

PollData_Design_PollDesign_Background

Used in: PollData_Design_PollDesign

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
PollData_Background_ColorVariant	COLOR
PollData_Background_GradientVariant	GRADIENT
PollData_Background_ImageVariant	IMAGE

PollData_Background_ColorVariant

Used in: PollData_Design_PollDesign_Background

Field	Type	Description
type Required	"COLOR"
color	string format COLOR_HEX	The background color in a hexademical value.

PollData_Background_ImageVariant

Used in: PollData_Design_PollDesign_Background

Field	Type	Description
type Required	"IMAGE"
image	Media	Image to use for the background.

PollData_Background_GradientVariant

Used in: PollData_Design_PollDesign_Background

Field	Type	Description
type Required	"GRADIENT"
gradient	PollData_Design_PollDesign_Background_Gradient	Gradient background details.

PollData_Design_PollDesign_Background_Gradient

Used in: PollData_Background_GradientVariant

Field	Type	Description
angle	int32	Gradient angle in degrees.
startColor	string format COLOR_HEX	Start color as a hexadecimal value.
lastColor	string format COLOR_HEX	end color as a hexadecimal value.

PollData_Design_OptionDesign

Used in: PollData_Design

Field	Type	Description
borderRadius	int32	Border radius in pixels.

HtmlNode

Used in: RootNode

Incorporates external content, such as interactive maps, or entire web pages.

Field	Type	Description
type Required	"HTML"	Node type. Value: HTML
htmlData Required	HTMLData	HTML details.
id	string format NODE_ID	Node ID.

HTMLData

Used in: HtmlNode

Field	Type	Description
containerData	PluginContainerData	HTML node container styling.
source	enum: "HTML", "ADSENSE"	HTML code type. Possible values: - HTML: HTML code. - ADSENSE: A service provided by Google for serving advertisements on web pages.
url One Of	string	HTML code URL.
html One Of	string	HTML code.

Decorations

This section lists what type of styling you can apply for Text Nodes. You can apply several styles at once, but one type of decoration should not be applied more than once.

Decoration

Used in: TextNodeStyle, TextData

This type is Tagged Union with type field being the discriminating tag.

Variant	Tag value	Description
AnchorDecoration	ANCHOR	Clickable text in a hyperlink. Rendered in a different color, indicating that it is a link that users can click to navigate to section in the same page.
BoldDecoration	BOLD	Text that is styled to appear thicker and more prominent than normal text.
ColorDecoration	COLOR	Text that is styled using background and text colors. Note: This decoration requires the colorDecoration plugin.
FontSizeDecoration	FONT_SIZE	Text font size.
ItalicDecoration	ITALIC	Text that is styled to appear slanted or italicized, which is typically used for emphasis, citations, or to distinguish certain types of content.
LinkDecoration	LINK	Clickable text in a hyperlink. This text is what users see and click on to navigate to another web page or another resource. Note: This decoration requires the link plugin.
MentionDecoration	MENTION	A piece of text that mentions a specific user, often in social media platforms, forums, or content management systems. Note: This decoration requires the mention plugin.
SpoilerDecoration	SPOILER	Text that is styled to appear blurred. Note: This decoration requires the spoiler plugin.
UnderlineDecoration	UNDERLINE	Text that is styled with a line underneath it.

BoldDecoration

Used in: Decoration

Text that is styled to appear thicker and more prominent than normal text.

Field	Type	Description
type Required	"BOLD"	Decoration type. Value: BOLD
fontWeightValue	float32	Font weight. Values are from 100 to 900.

ItalicDecoration

Used in: Decoration

Text that is styled to appear slanted or italicized, which is typically used for emphasis, citations, or to distinguish certain types of content.

Field	Type	Description
type Required	"ITALIC"	Decoration type. Value: ITALIC
italicData	boolean	Whether to enable the italic text.

UnderlineDecoration

Used in: Decoration

Text that is styled with a line underneath it.

Field	Type	Description
type Required	"UNDERLINE"	Decoration type. Value: UNDERLINE
underlineData	boolean	Whether to enable the underlined text.

SpoilerDecoration

Used in: Decoration

Text that is styled to appear blurred.
Note: This decoration requires the spoiler plugin.

Field	Type	Description
type Required	"SPOILER"	Decoration type. Value: SPOILER
spoilerData	SpoilerData	Spoiler details.

SpoilerData

Used in: SpoilerDecoration

Field	Type	Description
id	string format NODE_ID	Node ID.

AnchorDecoration

Used in: Decoration

Clickable text in a hyperlink. Rendered in a different color, indicating that it is a link that users can click to navigate to section in the same page.

Field	Type	Description
type Required	"ANCHOR"	Decoration type. Value: ANCHOR
anchorData	AnchorData	Anchor details.

AnchorData

Used in: AnchorDecoration

Field	Type	Description
anchor	string	Target Node ID, where the user is redirected after clicking the anchor.

MentionDecoration

Used in: Decoration

A piece of text that mentions a specific user, often in social media platforms, forums, or content management systems.
Note: This decoration requires the mention plugin.

Field	Type	Description
type Required	"MENTION"	Decoration type. Value: MENTION
mentionData	MentionData	Anchor details.

MentionData

Used in: MentionDecoration

Field	Type	Description
name	string	The display name of the mentioned user.
slug	string	The username of the mentioned user, appearing after the "@" character.
id	string	ID of the mentioned user.

LinkDecoration

Used in: Decoration

Clickable text in a hyperlink. This text is what users see and click on to navigate to another web page or another resource.
Note: This decoration requires the link plugin.

Field	Type	Description
type Required	"LINK"	Decoration type. Value: LINK
linkData	LinkData	Link details.

LinkData

Used in: LinkDecoration

Field	Type	Description
link	Link	Link object.

ColorDecoration

Used in: Decoration

Text that is styled using background and text colors.
Note: This decoration requires the colorDecoration plugin.

Field	Type	Description
type Required	"COLOR"	Decoration type. Value: COLOR
colorData	ColorData	Color details.

ColorData

Used in: ColorDecoration

Field	Type	Description
background	string	Background color in a hexadecimal value.
foreground	string	Text color in a hexadecimal value.

FontSizeDecoration

Used in: Decoration

Text font size.

Field	Type	Description
type Required	"FONT_SIZE"	Decoration type. Value: FONT_SIZE
fontSizeData	FontSizeData	Font size details.

FontSizeData

Used in: FontSizeDecoration

Field	Type	Description
unit	enum: "PX", "EM"	Font size units. Possible values: - PX: Size in pixels. - EM: Relative to the font size of the element (2em means 2 times the size of the current font)
value	float32	Font size value.

Metadata

Metadata is used to tell the information about the Ricos document itself, like a version. Can be skipped.

Metadata

Used in: RicosDocument

Field	Type	Description
version	uint32	Ricos document version.
id Deprecated	any
createdTimestamp Deprecated	any
updatedTimestamp Deprecated	any

Document Styles

DocumentStyle

Used in: RicosDocument

This object sets a default styling for a type of node throughout the entire Ricos Document. For example, we can set the text color for all Heading 1 nodes. You can override the styling of Text nodes separately using Decorations.

Field	Type	Description
headerOne	TextNodeStyle	Style for the H1 nodes.
headerTwo	TextNodeStyle	Style for the H2 nodes.
headerThree	TextNodeStyle	Style for the H3 nodes.
headerFour	TextNodeStyle	Style for the H4 nodes.
headerFive	TextNodeStyle	Style for the H5 nodes.
headerSix	TextNodeStyle	Style for the H6 nodes.
paragraph	TextNodeStyle	Style for the paragraph nodes.
blockquote	TextNodeStyle	Style for the block quote nodes.
codeBlock	TextNodeStyle	Style for the codeblock nodes.

TextNodeStyle

Used in: DocumentStyle

Field	Type	Description
decorations	Array <Decoration>	Decorations for text nodes.
nodeStyle	NodeStyle	Node style, such as padding. Note: This node requires the lineSpacing plugin.
lineHeight	string	Text line height.

Common Types

Types listed in this section are commonly used in other types.

ContainerData

This object defines the layout of node container that is used by videos, galleries, HTML, images, polls, and so on.

PluginContainerData

Used in: VideoData, DividerData, FileData, GalleryData, GIFData, HTMLData, ImageData, LinkPreviewData, PollData, ButtonData, CollapsibleListData, TableData, EmbedData, AudioData

Field	Type	Description
width	PluginContainerData_Width	Node width in a container when it's displayed.
alignment	enum: "CENTER", "LEFT", "RIGHT"	Node alignment in its container. Possible values: - CENTER - LEFT - RIGHT
spoiler	PluginContainerData_Spoiler	Spoiler cover settings.
height	PluginContainerData_Height	Node height in a container when it's displayed.
textWrap	boolean	Whether the text should wrap around the node when it's displayed. If textWrap is false, the node takes up the width of its container. Default: true for all node types except DIVIDER.

PluginContainerData_Spoiler

Used in: PluginContainerData

Field	Type	Description
enabled	boolean	Whether the spoiler cover is enabled. Default: false
description	string	Description displayed on top of the spoiler cover.
buttonText	string	Text of a button that removes the spoiler cover.

PluginContainerData_Width

Used in: PluginContainerData

The width of the node when it's displayed.

Field	Type	Description
size One Of	enum: "CONTENT", "SMALL", "ORIGINAL", "FULL_WIDTH"	Width size of a node in a container. Possible values: - CONTENT: The width of the container matches the content width. - SMALL: A small width. - ORIGINAL: The width of the container matches the original image width. Note: This value is applicable for imageData containers only. FULL_WIDTH: The image container takes up the full width of the screen. Note: This value is applicable for imageData containers only.
custom One Of	string	A custom width value in pixels.

PluginContainerData_Height

Used in: PluginContainerData

Field	Type	Description
custom	string	A custom height value in pixels.

NodeStyle

Used in: TextNodeStyle, ParagraphNode, HeadingNode, BlockquoteNode, CodeBlockNode

Field	Type	Description
paddingTop	string	The top padding value in pixels.
paddingBottom	string	The bottom padding value in pixels.
backgroundColor Deprecated	string

TextStyle

Used in: ParagraphData, HeadingData, CodeBlockData

Field	Type	Description
textAlignment	enum: "AUTO", "LEFT", "RIGHT", "CENTER", "JUSTIFY"	Text alignment. Possible values: - AUTO: Text alligns itself automatically. - LEFT: Text is aligned to the left. - RIGHT: Text is aligned to the right. - CENTER: Text is centered. - JUSTIFY: Text is justified to both margins. Default: AUTO.
lineHeight	string	Vertical spacing between lines of text in an element.

Link

Used in: ImageData, LinkPreviewData, ButtonData, LinkData, GalleryData_Item_Image

Link object.

Field	Type	Description
url Required One Of	string	Absolute URL for the linked document.
anchor Required One Of	string	Target Node ID, where the user is redirected after clicking the anchor.
target	enum: "SELF", "BLANK", "PARENT", "TOP"	The HTML target attribute value for the link. This property defines where the linked document opens. Possible values: SELF - Default. Opens the linked document in the same frame as the link. BLANK - Opens the linked document in a new browser tab or window. PARENT - Opens the linked document in the link's parent frame. TOP - Opens the linked document in the full body of the link's browser tab or window.
rel	Link_Rel	This object specifies the relationship between the current document and the linked document.

Link_Rel

Used in: Link

Field	Type	Description
nofollow	boolean	Indicates to search engine crawlers not to follow the link. Default: false
sponsored	boolean	Indicates to search engine crawlers that the link is a paid placement such as sponsored content or an advertisement. Default: false
ugc	boolean	Indicates that this link is user-generated content and isn't necessarily trusted or endorsed by the page author. Default: false
noreferrer	boolean	Indicates that this link protects referral information from being passed to the target website.

FileSource

Used in: FileData, Media

File source object.

Field	Type	Description
url Required One Of	string	Absolute URL for the file's source.
id Required One Of	string	ID that's resolved to a URL by a resolver function.
private	boolean	Indicates whether the file's source is private. Default: false

Media

Used in: VideoData, ImageData, AudioData, PollData_Poll, AppEmbedDataProduct, AppEmbedDataEvent, AppEmbedDataBooking, GalleryData_Item_Image, GalleryData_Item_Video, PollData_Poll_Option, PollData_Background_ImageVariant

Field	Type	Description
src Required	FileSource	Media data source.
width	int32	Media width in pixels.
height	int32	Media height in pixels.
duration	float64	Media duration in seconds. Only relevant for audio and video files.

Explanations

Node Ids

Each node ID should be a unique string in the document. These IDs are used primarily to identify nodes for anchor behavior, and sometimes as HTML IDs to execute rendering.

The node ID is mainly used for anchor behavior, as illustrated in the AnchorDecoration example. The editor automatically generates the ID. If you are creating the Ricos Document via an API, you must manually add this ID if necessary.

Plugins

This article describes the full reference of Ricos Document schema. However, some parts of the Ricos document are operational only when the corresponding plugins in the API are enabled. For example ImageNode can be used only when the image plugin is enabled. A complete list of supported plugins is available in the field descriptions of each API that supports the Ricos Document type.

Full list of plugins which have effect on Ricos Document: actionButton, audio, codeBlock, collapsibleList, divider, file, gallery, giphy, html, image, lineSpacing, linkButton, linkPreview, link, mention, poll, spoiler, table, textColor, textHighlight, appEmbed, video,

Tagged unions

Tagged unions are fundamental to the Ricos Document. They accommodate various nodes with different shapes that can occupy the same space. At the root level, there can be more than 10 different nodes. How do we unambiguously determine which node is which? Tagged unions facilitate this by incorporating a common field present in every node’s object. In the Ricos Document, this field is named type but may also be referred to as ‘tag.’ Each node (or decoration) contains this same field, yet each possesses a distinct string value in it. This differentiation allows for easy identification of each node, despite them occupying the “same space.”

Learn more about them on Wikipedia

Formats

Format	Description
WEB_URL	A URL that starts with http:// or https://.
COLOR_HEX	A color in hexadecimal RGB or RGBA format, such as #FF0000 or #FF000050. Accepts shorthands like #F00 and #F005
NODE_ID	A unique identifier for a node. It must start with a letter and can contain only letters, numbers, hyphens, and underscores.

Validations

Validation	Description
minItems	Minimum number of items in array
maxItems	Maximum number of items in array
minLength	Minimum length of string
maxLength	Maximum length of string
uniqueTags	The items in array must have unique union tags on them

Patterns

Most node children are arrays, which can contain zero or more of the specified nodes in any order. However, there are exceptions like ListItemNode and CollapsibleItem, which have specific restrictions on how these arrays can be structured. For example, a CollapsibleItem must contain one CollapsibleItemTitleNode and one CollapsibleItemBodyNode. A (ListItemNode)[#listitemnode) must have a (ParagraphNode)[#paragraphnode] or (HeadingNode)[#headingnode) as the first child, followed by any number of paragraphs, headings, or lists. The strict pattern description uses syntax similar to regular expressions:

• * indicates any number of items
• + indicates one or more items
• () parentheses are used for groups and enclose item tags that can be used interchangeably.

For specific pattern descriptions, refer to the properties table containing the patterned field above.

One Of

Fields in the One Of groups have a constraint that only one of them can be set at the same time.

The variation Required One Of adds another constraint: one (and still at most one) of the fields must be set.