Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Migration FAQ and Migration guide.
API reference
API reference

openDesign

API reference for the openDesign method.
This version of the API is in beta. Beta APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Reads a specified part of the user's design and returns all elements in that part.

Parameters

optionsDesignContextOptions
REQUIRED

Options for configuring which part of a design to read.

Properties of options
typestring
REQUIRED

The type of context.

This must be "current_page".

callbackfunction
REQUIRED

Parameters

draftCurrentPageResult
REQUIRED

The result of reading part of a design when the context is the current page.

Properties of draft
savefunction
REQUIRED
  • Any changes to the draft are only reflected in the design after this method is called.
  • Once this method is called, further changes to the draft are not possible.

Returns

Promise<void>

pageFixedPage
REQUIRED

The current page of the design.

Properties of page
typestring
REQUIRED

The type of page.

This must be "fixed".

lockedboolean
REQUIRED

If true, the page is locked and cannot be modified.

dimensionsundefined | Dimensions
REQUIRED

The dimensions of the page. dimensions is undefined for whiteboard pages.

Properties of dimensions
widthnumber
REQUIRED

A width, in pixels.

heightnumber
REQUIRED

A height, in pixels.

backgroundundefined | Fill
REQUIRED

The background of the page. background is undefined for whiteboard pages.

Properties of background
mediaundefined | MediaFill
REQUIRED

The media fill for the path, if any.

An image that fills the interior of a path.

typestring
REQUIRED

The type of media.

This must be "image".

imageRefImageRef
REQUIRED

A unique identifier that points to an image asset in Canva's backend.

flipXboolean
REQUIRED

If true, the image is flipped horizontally.

flipYboolean
REQUIRED

If true, the image is flipped vertically.

A video that fills the interior of a path.

typestring
REQUIRED

The type of media.

This must be "video".

videoRefVideoRef
REQUIRED

A unique identifier that points to a video asset in Canva's backend.

flipXboolean
REQUIRED

If true, the video is flipped horizontally.

flipYboolean
REQUIRED

If true, the video is flipped vertically.

colorundefined | ColorFill
REQUIRED

The color fill for the path, if any.

A solid color that fills the interior of a path.

typestring
REQUIRED

The type of color.

This must be "solid".

colorstring
REQUIRED

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestring
REQUIRED

The type of element.

This must be "unsupported".

elementsList<FixedElement>
REQUIRED

The elements on the page.

Elements are rendered in the order they appear in the list. Later elements appear on top of earlier ones.

Properties of elements
countfunction
REQUIRED

Returns

The number of items.

number

toArrayfunction
REQUIRED

Returns

An array containing all items. The items are the same as in the list.

readonly T[]

forEachfunction
REQUIRED

Parameters

callbackForEachCallback<T>
REQUIRED

The function to run for each item.

Parameters

itemT
REQUIRED

The current item in the list.

indexnumber
REQUIRED

The index of the current item.

Returns

void

Returns

void

filterfunction
REQUIRED

Parameters

filterFilterPredicate<T>
REQUIRED

A function that tests each item. Returns true to keep the item.

Parameters

itemT
REQUIRED

The item to test.

Returns

true if the item should be included, otherwise false.

boolean

Returns

An array of items that passed the test.

readonly T[]

insertBeforefunction
REQUIRED

Parameters

refundefined | T
REQUIRED

The existing item to place the new item before. If ref is undefined, the new item is added at the end of the list. If ref does not exist in the list, the operation fails.

itemT
REQUIRED

The item to add. A copy of this item will be inserted.

Returns

The added item, or undefined if the operation failed.

undefined | T

insertAfterfunction
REQUIRED

Parameters

refundefined | T
REQUIRED

The existing item to place the new item after. If ref is undefined, the new item is added at the end of the list. If ref does not exist in the list, the operation fails.

itemT
REQUIRED

The item to add. A copy of this item will be inserted.

Returns

The added item, or undefined if the operation failed.

undefined | T

moveBeforefunction
REQUIRED

Parameters

refundefined | T
REQUIRED

The existing item to move the item before. If ref is undefined, the item is moved to the end of the list. If ref does not exist in the list, the operation fails.

itemT
REQUIRED

The item to move. The operation fails if the item is not already in the list.

Returns

void

moveAfterfunction
REQUIRED

Parameters

refundefined | T
REQUIRED

The existing item to move the item after. If ref is undefined, the item is moved to the end of the list. If ref does not exist in the list, the operation fails.

itemT
REQUIRED

The item to move. The operation fails if the item is not already in the list.

Returns

void

deletefunction
REQUIRED

Parameters

itemT
REQUIRED

The item to remove from the list.

Returns

void

helpersobject
REQUIRED
Properties of helpers
elementBuilderElementBuilder
REQUIRED

Provides methods for creating elements.

These methods don't add the elements to the design. They only return elements that can be added to a design, such as with the insertAfter method.

Properties of elementBuilder
createRectElementfunction
REQUIRED

Parameters

optsCreateRectElementOpts
REQUIRED

Options for creating the rect element.

Properties of opts
fillFillOpts
OPTIONAL
colorColorFillOpts
REQUIRED
mediaMediaFillOpts
OPTIONAL

Options for creating an image fill in the element builder

Options for creating a video fill in the element builder

mediaMediaFillOpts
REQUIRED

Options for creating an image fill in the element builder

Options for creating a video fill in the element builder

colorColorFillOpts
OPTIONAL
strokeStrokeOpts
OPTIONAL
Properties of stroke
colorColorFillOpts
REQUIRED
weightnumber
REQUIRED

The weight (thickness) of the stroke.

  • Minimum: 0
  • Maximum: 100

Returns

An element that renders a rectangle.

The rectangle can be filled with image content, video content, or a solid color.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

If true, the element is locked and cannot be modified.

topnumber

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
leftnumber

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
rotationnumber

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180
transparencynumber

Transparency as a percentage.

  • Minimum: 0
  • Maximum: 1
typestring

The type of content.

This must be "rect".

fillFill

The appearance of the rectangle's interior.

Properties of fill
mediaundefined | MediaFill

The media fill for the path, if any.

An image that fills the interior of a path.

typestring

The type of media.

This must be "image".

imageRefImageRef

A unique identifier that points to an image asset in Canva's backend.

flipXboolean

If true, the image is flipped horizontally.

flipYboolean

If true, the image is flipped vertically.

A video that fills the interior of a path.

typestring

The type of media.

This must be "video".

videoRefVideoRef

A unique identifier that points to a video asset in Canva's backend.

flipXboolean

If true, the video is flipped horizontally.

flipYboolean

If true, the video is flipped vertically.

colorundefined | ColorFill

The color fill for the path, if any.

A solid color that fills the interior of a path.

typestring

The type of color.

This must be "solid".

colorstring

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestring

The type of element.

This must be "unsupported".

strokeStroke

The outline of the rectangle.

Properties of stroke
weightnumber

The weight (thickness) of the stroke.

  • Minimum: 0
  • Maximum: 100
colorColorFill

The color of the stroke.

A solid color that fills the interior of a path.

typestring

The type of color.

This must be "solid".

colorstring

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestring

The type of element.

This must be "unsupported".

createShapeElementfunction
REQUIRED

Parameters

optsCreateShapeElementOpts
REQUIRED

Options for creating the shape element.

Properties of opts
pathsShapePathOpts[]
REQUIRED
Properties of paths
fillFillOpts
OPTIONAL
colorColorFillOpts
REQUIRED
mediaMediaFillOpts
OPTIONAL

Options for creating an image fill in the element builder

Options for creating a video fill in the element builder

mediaMediaFillOpts
REQUIRED

Options for creating an image fill in the element builder

Options for creating a video fill in the element builder

colorColorFillOpts
OPTIONAL
strokeStrokeOpts
OPTIONAL
Properties of stroke
colorColorFillOpts
REQUIRED
weightnumber
REQUIRED

The weight (thickness) of the stroke.

  • Minimum: 0
  • Maximum: 100
dstring
REQUIRED

The shape of the path.

This is similar to the d attribute of an SVG's path element, with some limitations:

  • Must start with an M command.
  • Only one M command is allowed.
  • Q and T commands are not permitted.
  • The path must be closed using a Z command or matching start and end coordinates.

Returns

An element that renders a vector shape.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

If true, the element is locked and cannot be modified.

topnumber

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
leftnumber

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
rotationnumber

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180
transparencynumber

Transparency as a percentage.

  • Minimum: 0
  • Maximum: 1
typestring

The type of content.

This must be "shape".

viewBoxAlignedBox

The scale and cropping of the shape.

Properties of viewBox
topnumber

The distance of the shape from the top edge of the element, in pixels.

leftnumber

The distance of the shape from the left edge of the element, in pixels.

widthnumber

The width of the view box, in pixels.

heightnumber

The height of the view box, in pixels.

pathsReadableList<Path>

The paths that define the structure of the shape.

  • Must have between 1 and 30 paths.
  • Total size of all paths must not exceed 2kb.
  • Maximum of 6 unique fill colors across all paths.
Properties of paths
countfunction

Returns

The number of items.

number

toArrayfunction

Returns

An array containing all items. The items are the same as in the list.

readonly T[]

forEachfunction

Parameters

callbackForEachCallback<T>
REQUIRED

The function to run for each item.

Parameters

itemT
REQUIRED

The current item in the list.

indexnumber
REQUIRED

The index of the current item.

Returns

void

Returns

void

filterfunction

Parameters

filterFilterPredicate<T>
REQUIRED

A function that tests each item. Returns true to keep the item.

Parameters

itemT
REQUIRED

The item to test.

Returns

true if the item should be included, otherwise false.

boolean

Returns

An array of items that passed the test.

readonly T[]

createEmbedElementfunction
REQUIRED

Parameters

optsCreateEmbedElementOpts
REQUIRED

Options for creating the embed element.

Returns

An element that embeds rich media, such as a YouTube video.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

If true, the element is locked and cannot be modified.

topnumber

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
leftnumber

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
rotationnumber

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180
transparencynumber

Transparency as a percentage.

  • Minimum: 0
  • Maximum: 1
typestring

The type of content.

This must be "embed".

urlstring

The URL of the rich media.

This URL must be supported by the Iframely API.

createTextElementfunction
REQUIRED

Parameters

optsCreateTextElementOpts
REQUIRED

Options for creating the text element.

Returns

An element that renders text content.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

If true, the element is locked and cannot be modified.

topnumber

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
leftnumber

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
rotationnumber

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180
transparencynumber

Transparency as a percentage.

  • Minimum: 0
  • Maximum: 1
typestring

The type of content.

This must be "text".

textRichtextRange

The text content.

Properties of text
formatParagraphfunction

Formats all of the paragraphs that overlap the given bounds.

  • The \n character indicates the end of a paragraph.
  • All paragraphs that overlap the provided bounds will be formatted in their entirety.

Parameters

boundsBounds
REQUIRED

The segment of the range on which to apply the formatting.

Properties of bounds
indexnumber
REQUIRED

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
REQUIRED

The number of characters in the segment, starting from the index.

formattingRichtextFormatting
REQUIRED

The formatting to apply to the paragraph(s).

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"
fontRefFontRef
OPTIONAL

A unique identifier that points to a font asset in Canva's backend.

fontSizenumber
OPTIONAL

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.
  • Minimum: 1
  • Maximum: 100
textAlignstring
OPTIONAL

The alignment of the text.

Default Value: "start"

The available options include:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumber
OPTIONAL

The list indentation level of the paragraph.

listMarkerstring
OPTIONAL

The appearance of list item markers.

This property only has an effect if listLevel is greater than 0.

Default Value: "none"

The available options include:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"

Returns

void

formatTextfunction

Formats a region of text with inline formatting properties.

Parameters

boundsBounds
REQUIRED

The segment of the range on which to apply the formatting.

Properties of bounds
indexnumber
REQUIRED

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
REQUIRED

The number of characters in the segment, starting from the index.

formattingInlineFormatting
REQUIRED

The formatting to apply to the text.

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunction

Appends the specified characters to the end of the range.

Parameters

charactersstring
REQUIRED

The characters to append to the richtext range.

formattingInlineFormatting
OPTIONAL

Options for formatting inline richtext.

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

boundsBounds

A segment of a richtext range.

Properties of bounds
indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

replaceTextfunction

Replaces a region of text with the specified characters.

Parameters

boundsBounds
REQUIRED

The segment of the range to replace.

Properties of bounds
indexnumber
REQUIRED

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
REQUIRED

The number of characters in the segment, starting from the index.

charactersstring
REQUIRED

The replacement characters.

formattingInlineFormatting
OPTIONAL

The formatting to apply to the replaced text.

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

boundsBounds

The bounds of the replacement characters within the updated range.

Properties of bounds
indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

readPlaintextfunction

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunction

Returns the current state of the richtext as one or more text regions. Each region is an object that contains the text content and its formatting.

Returns

textstring

The plaintext content of the region.

formattingPartial<RichtextFormatting>
OPTIONAL

The formatting of the region.

createRichtextRangefunction
REQUIRED

Returns

Provides methods for interacting with a range of formatted text.

formatParagraphfunction

Formats all of the paragraphs that overlap the given bounds.

  • The \n character indicates the end of a paragraph.
  • All paragraphs that overlap the provided bounds will be formatted in their entirety.

Parameters

boundsBounds
REQUIRED

The segment of the range on which to apply the formatting.

Properties of bounds
indexnumber
REQUIRED

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
REQUIRED

The number of characters in the segment, starting from the index.

formattingRichtextFormatting
REQUIRED

The formatting to apply to the paragraph(s).

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"
fontRefFontRef
OPTIONAL

A unique identifier that points to a font asset in Canva's backend.

fontSizenumber
OPTIONAL

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.
  • Minimum: 1
  • Maximum: 100
textAlignstring
OPTIONAL

The alignment of the text.

Default Value: "start"

The available options include:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumber
OPTIONAL

The list indentation level of the paragraph.

listMarkerstring
OPTIONAL

The appearance of list item markers.

This property only has an effect if listLevel is greater than 0.

Default Value: "none"

The available options include:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"

Returns

void

formatTextfunction

Formats a region of text with inline formatting properties.

Parameters

boundsBounds
REQUIRED

The segment of the range on which to apply the formatting.

Properties of bounds
indexnumber
REQUIRED

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
REQUIRED

The number of characters in the segment, starting from the index.

formattingInlineFormatting
REQUIRED

The formatting to apply to the text.

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunction

Appends the specified characters to the end of the range.

Parameters

charactersstring
REQUIRED

The characters to append to the richtext range.

formattingInlineFormatting
OPTIONAL

Options for formatting inline richtext.

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

boundsBounds

A segment of a richtext range.

Properties of bounds
indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

replaceTextfunction

Replaces a region of text with the specified characters.

Parameters

boundsBounds
REQUIRED

The segment of the range to replace.

Properties of bounds
indexnumber
REQUIRED

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber
REQUIRED

The number of characters in the segment, starting from the index.

charactersstring
REQUIRED

The replacement characters.

formattingInlineFormatting
OPTIONAL

The formatting to apply to the replaced text.

Properties of formatting
colorstring
OPTIONAL

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

boundsBounds

The bounds of the replacement characters within the updated range.

Properties of bounds
indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

readPlaintextfunction

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunction

Returns the current state of the richtext as one or more text regions. Each region is an object that contains the text content and its formatting.

Returns

textstring

The plaintext content of the region.

formattingPartial<RichtextFormatting>
OPTIONAL

The formatting of the region.

Returns

void or Promise<void>

Returns

Promise<void>