@wordpress/rich-text
Advanced tools
This module contains helper functions to convert HTML or a DOM tree into a rich text value and back, and to modify the value with functions that are similar to String methods, plus some additional ones for formatting.
Install the module
npm install @wordpress/rich-text
This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.
# applyFormat
Apply a format object to a Rich Text value from the given startIndex to the
given endIndex. Indices are retrieved from the selection if none are
provided.
Parameters
Object: Value to modify.Object: Format to apply.[number]: Start index.[number]: End index.Returns
Object: A new value with the format applied.# concat
Combine all Rich Text values into one. This is similar to
String.prototype.concat.
Parameters
...Object: Objects to combine.Returns
Object: A new value combining all given records.# create
Create a RichText value from an Element tree (DOM), an HTML string or a
plain text string, with optionally a Range object to set the selection. If
called without any input, an empty value will be created. If
multilineTag is provided, any content of direct children whose type matches
multilineTag will be separated by two newlines. The optional functions can
be used to filter out content.
A value will have the following shape, which you are strongly encouraged not to modify without the use of helper functions:
{
text: string,
formats: Array,
replacements: Array,
?start: number,
?end: number,
}
As you can see, text and formatting are separated. text holds the text,
including any replacement characters for objects and lines. formats,
objects and lines are all sparse arrays of the same length as text. It
holds information about the formatting at the relevant text indices. Finally
start and end state which text indices are selected. They are only
provided if a Range was given.
Parameters
[Object]: Optional named arguments.[Element]: Element to create value from.[string]: Text to create value from.[string]: HTML to create value from.[Range]: Range to create value from.[string]: Multiline tag if the structure is multiline.[Array]: Tags where lines can be found if nesting is possible.Returns
Object: A rich text value.# getActiveFormat
Gets the format object by type at the start of the selection. This can be used to get e.g. the URL of a link format at the current selection, but also to check if a format is active at the selection. Returns undefined if there is no format at the selection.
Parameters
Object: Value to inspect.string: Format type to look for.Returns
(Object|undefined): Active format object of the specified type, or undefined.# getActiveObject
Gets the active object, if there is any.
Parameters
Object: Value to inspect.Returns
?Object: Active object, or undefined.# getTextContent
Get the textual content of a Rich Text value. This is similar to
Element.textContent.
Parameters
Object: Value to use.Returns
string: The text content.# insert
Insert a Rich Text value, an HTML string, or a plain text string, into a
Rich Text value at the given startIndex. Any content between startIndex
and endIndex will be removed. Indices are retrieved from the selection if
none are provided.
Parameters
Object: Value to modify.(Object|string): Value to insert.[number]: Start index.[number]: End index.Returns
Object: A new value with the value inserted.# insertObject
Insert a format as an object into a Rich Text value at the given
startIndex. Any content between startIndex and endIndex will be
removed. Indices are retrieved from the selection if none are provided.
Parameters
Object: Value to modify.Object: Format to insert as object.[number]: Start index.[number]: End index.Returns
Object: A new value with the object inserted.# isCollapsed
Check if the selection of a Rich Text value is collapsed or not. Collapsed
means that no characters are selected, but there is a caret present. If there
is no selection, undefined will be returned. This is similar to
window.getSelection().isCollapsed().
Parameters
Object: The rich text value to check.Returns
(boolean|undefined): True if the selection is collapsed, false if not, undefined if there is no selection.# isEmpty
Check if a Rich Text value is Empty, meaning it contains no text or any objects (such as images).
Parameters
Object: Value to use.Returns
boolean: True if the value is empty, false if not.# join
Combine an array of Rich Text values into one, optionally separated by
separator, which can be a Rich Text value, HTML string, or plain text
string. This is similar to Array.prototype.join.
Parameters
Array<Object>: An array of values to join.[(string|Object)]: Separator string or value.Returns
Object: A new combined value.# registerFormatType
Registers a new format provided a unique name and an object defining its behavior.
Parameters
string: Format name.Object: Format settings.string: The HTML tag this format will wrap the selection with.[string]: A class to match the format.string: Name of the format.Function: Should return a component for the user to interact with the new registered format.Returns
(WPFormat|undefined): The format, if it has been successfully registered; otherwise undefined.# remove
Remove content from a Rich Text value between the given startIndex and
endIndex. Indices are retrieved from the selection if none are provided.
Parameters
Object: Value to modify.[number]: Start index.[number]: End index.Returns
Object: A new value with the content removed.# removeFormat
Remove any format object from a Rich Text value by type from the given
startIndex to the given endIndex. Indices are retrieved from the
selection if none are provided.
Parameters
Object: Value to modify.string: Format type to remove.[number]: Start index.[number]: End index.Returns
Object: A new value with the format applied.# replace
Search a Rich Text value and replace the match(es) with replacement. This
is similar to String.prototype.replace.
Parameters
Object: The value to modify.(RegExp|string): A RegExp object or literal. Can also be a string. It is treated as a verbatim string and is not interpreted as a regular expression. Only the first occurrence will be replaced.(Function|string): The match or matches are replaced with the specified or the value returned by the specified function.Returns
Object: A new value with replacements applied.# slice
Slice a Rich Text value from startIndex to endIndex. Indices are
retrieved from the selection if none are provided. This is similar to
String.prototype.slice.
Parameters
Object: Value to modify.[number]: Start index.[number]: End index.Returns
Object: A new extracted value.# split
Split a Rich Text value in two at the given startIndex and endIndex, or
split at the given separator. This is similar to String.prototype.split.
Indices are retrieved from the selection if none are provided.
Parameters
Object: Value to modify.[(number|string)]: Start index, or string at which to split.[number]: End index.Returns
Array: An array of new values.# toggleFormat
Toggles a format object to a Rich Text value at the current selection.
Parameters
Object: Value to modify.Object: Format to apply or remove.Returns
Object: A new value with the format applied or removed.# toHTMLString
Create an HTML string from a Rich Text value. If a multilineTag is
provided, text separated by a line separator will be wrapped in it.
Parameters
Object: Named argements.Object: Rich text value.[string]: Multiline tag.Returns
string: HTML string.# unregisterFormatType
Unregisters a format.
Parameters
string: Format name.Returns
(WPFormat|undefined): The previous format value, if it has been successfully unregistered; otherwise undefined.
FAQs
Rich text value and manipulation API.
The npm package @wordpress/rich-text receives a total of 68,676 weekly downloads. As such, @wordpress/rich-text popularity was classified as popular.
We found that @wordpress/rich-text demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 23 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.