Library reference
Contents
The React4xp library (Enonic Market) exposes a few functions and a React4xp object that can be used in your Enonic app.
For the SSR engine and hydration, and for compilation and runtime configuration, see the respective chapters.
Usage
Add library dependency
Add the lib-react4xp dependency to your project with a single line:
dependencies {
include "com.enonic.lib:lib-react4xp:${libVersion}"
}
Replace ${libVersion} with the desired version of lib-react4xp. For a full project setup (including the @enonic/react4xp build integration), see the library docs on GitHub.
Import library
Add the import statement to your script file.
import {React4xp} from '/lib/enonic/react4xp';
Individual functions can also be imported directly, e.g. import {render, processHtml} from '/lib/enonic/react4xp'.
Mount the API
React4XP 7 (and newer) uses XP 8’s universal API functionality, serving its compiled assets and SSR endpoints through a react4xp web API. This API must be mounted in the context descriptor (i.e. site, webapp or admin tool where React4XP is used). Parts, layouts and pages inherit it from their context and don’t declare it themselves. Without it, the browser can’t load React4XP’s assets and rendering won’t work.
apis:
- "react4xp"
Invocation example
A minimal controller passes an entry, props, and the request to render. The return value is an XP response object you return directly:
import {React4xp} from '/lib/enonic/react4xp';
import type {Request} from '@enonic-types/core';
export function get(request: Request) {
// 'my-entry' is a JsxPath to a compiled react component
return React4xp.render('my-entry', {greeting: 'Hello world'}, request);
}
render returns a {body, pageContributions} response object, so returning it straight from the controller both renders server-side and adds everything the browser needs to activate the react app. Each function and its options are documented below.
Functions
render
All-in-one shorthand function for a lot of use cases. Covers both client- and serverside rendering.
Inserts a react component into an (optional) pre-existing HTML string and adds any necessary page contributions to make all work: links to assets, both shared and specific to the entry, and a client-side JS call (render or hydrate in the client wrapper) that activates the react component in the browser.
Parameters
| Name | Type | Description |
|---|---|---|
|
|
string | component object |
|
|
|
object |
Optional. Data model passed into the react component. JS object must be serializable (no functions can be passed). Corresponds to the model argument in |
|
|
Optional (but required for react activation). Include to detect the rendering mode inside/outside Content Studio: inside Content Studio there should be only a static serverside-rendering, no browser react activation (or client-side rendering), only returning get an HTML visualization with the initial |
|
|
|
object |
Optional. Additional options to control the rendering (see below). |
The options object accepts these properties, all optional:
| Name | Type | Description |
|---|---|---|
|
|
string |
Optional. ID of the component, targeting the ID of an element in |
|
|
string |
Optional. Valid HTML to serve as container for the react content. On server-side rendering the output is inserted into the matching- |
|
|
object |
Optional. Existing page contributions to add. These are added before the ones rendered by this call (within each section |
|
|
boolean |
Optional. When SSR is true, choose whether to hydrate. Defaults to |
|
|
boolean |
Optional. Switch between client-side and server-side rendering for this particular rendering; other renderings are not affected. If falsy, you get server-side rendering and the client calls |
|
|
boolean |
Optional. Whether to render the surrounding container element around the target element. |
|
|
|
Optional. URL type for assets: server-relative or absolute. Defaults to |
|
|
boolean | string |
Optional. Force a unique target id. Pass a string to set the id explicitly, or |
Returns
Returns an XP response object with these main attributes:
| Name | Type | Description |
|---|---|---|
|
|
string, rendered HTML |
HTML output. The root of this HTML is always a surrounding container HTML that will have a matching-ID target element in it somewhere (an element matching the ID of the clientside call to Inside that matching-ID element, there will be a serverside rendering of the entry (with the initial props from |
|
|
object |
Regular page contributions. Includes everything the browser needs to activate (or client-side render) the react component: script tags with urls to auto-compiled assets for the entry and its dependencies, a client-side react4xp wrapper asset and an activating client-wrapper call. Urls point to React4xp’s own optimized asset services. Also included before this, are any input |
Request and automated behavior
.render is intended to be convenient to work with and safely wrap around some common corner cases. It automates a little bit of behavior, depending on the request object argument (which stems from the XP controller):
render with request:
React4xp.render(entry, props, request);
React4xp.render(entry, props, request, options); // ...etc etc
If request is supplied, viewing context is detected from request.mode: is rendering happening inside or outside of Content Studio edit mode?
-
Inside Content Studio edit mode,
.renderwill always select serverside rendering (no matter whatssris) and skip JS dependency assets and the clientsiderender/hydratetrigger (but still supply other dependencies, such as CSS). This ensures that a static HTML placeholder rendering is visible inside Content Studio’s edit mode, but keeps react from being activated. This is by design: preventing the possibility that react code might intervene with the UX of Content Studio itself. -
Outside Content Studio edit mode, the rendering will be activated as a react app (i.e. all pageContributions are rendered). Also,
ssris used, so if this isfalse, serverside rendering is skipped. The`and `renderis called in the client instead ofhydrate.
Also, when request is used, .render will output error messages from SSR in error containers and browser consoles (except in live view mode, where error containers and browser log are more generic: shown without the specific messages).
render without request:
React4xp.render(entry, props);
React4xp.render(entry, props, null);
React4xp.render(entry, props, undefined, options); // ...etc etc
Omitting request from render has the effect of always rendering as if it’s inside Content Studio (see above). Again, this is by design - trying to make sure that a viewable and safe rendering is always returned, even when viewing context can’t be determined.
However, it also means that hydrate and ssr options are ignored (you always get SSR without Hydration), and there is no call to activate the react app in the browser. Basically, it’s as if TSX/JSX is used as a pure, static HTML templating language (same as XP’s Thymeleaf renderer - which shares the same basic signature).
When request is omitted, .render will never output error messages from SSR in error containers or browser console.
Examples
processHtml
Transforms raw rich text HTML (typically the value of an HtmlArea input) into the RichTextData format consumed by the RichText component from @enonic/react-components - resolving links, sizing images and preparing macros for rendering. Typically used inside a data processor, like in the Pages chapter.
Parameters
The params object accepts the same parameters as XP’s portal.processHtml, plus dataFetcher and component:
| Name | Type | Description |
|---|---|---|
|
|
string |
The raw HTML string to process. |
|
|
DataFetcher |
The dataFetcher instance - inside a processor, pass |
|
|
component object |
Optional. The component currently being processed ( |
|
|
number[] |
Optional. Widths (in pixels) of scaled image variants to generate, used for the |
|
|
string |
Optional. Value for the |
|
|
|
Optional. URL type of the processed links. Either server (server-relative URL, default) or absolute. |
Returns
Returns a RichTextData object, ready to be passed to the data prop of the RichText react component.
Example
import {PartComponent} from '@enonic-types/core';
import type {ComponentProcessor} from '@enonic-types/lib-react4xp/DataFetcher';
import {processHtml} from '/lib/enonic/react4xp';
export const paragraphProcessor: ComponentProcessor<'com.enonic.app.hmdb:paragraph'> = (params) => {
const component = params.component as PartComponent;
const text = component.config?.text as string;
return {
text: text ? processHtml({
value: text,
imageWidths: [200, 400, 800],
dataFetcher: params.dataFetcher,
component: params.component
}) : '',
};
};
Classes
React4xp
More flexible and controllable than React4xp.render: create a data-holding react4xp object with the React4xp contructor, manipulate it or extract data from it, combine with other objects, and then later render it to an HTML body string and/or page contributions, separately. This is actually what React4xp.render does behind the scenes.
Call the two rendering methods from the same react4xp object. Remember, if using hydrate, ssr and/or request options, they should usually be the same value across the two corresponding calls. A typical (compact) usage example:
exports.get = function(request) => {
// Object constructor:
const myComponent = new React4xp('my-entry');
// ...read myComponent attributes and/or use its setter methods...
// const ssr = ...true or false...
// Call the rendering methods:
return {
body: myComponent.renderBody({
// ssr, etc
request
}),
pageContributions: myComponent.renderPageContributions({
// hydrate, ssr, etc
request
})
}; // ...etc, etc
}
See the custom flow syntax lesson to go more in depth.
The setter methods (below) are all optional; if not used, the object renders with empty values or placeholders where needed, along the same logic as render. They all return the data object itself, so you can chain them in a builder pattern: myComponent.setProps(…).setId(…). The order doesn’t matter - except for setId and uniqueId, which affect each other.
Constructor
const myComponent = new React4xp(entry);
Creates an initial react4xp data object from an entry.
| Name | Type | Description |
|---|---|---|
|
|
string | component object |
Reference to an entry: the react component to be rendered. Direct JsxPath string, or a |
Constructs a react4xp data object, which exposes the attributes and methods below.
Object attributes
Extract from the object the data that has been generated or set in it.
| Name | Type | Description |
|---|---|---|
|
|
string |
Target |
|
|
string |
jsxPath to the entry. |
|
|
object |
|
const targetElementId = myComponent.react4xpId;
setProps
myComponent.setProps(props);
Sets props for the entry.
| Name | Type | Description |
|---|---|---|
|
|
object |
|
setId
myComponent.setId(id);
Sets an ID - directly and literally, so uniqueness is up to you. This ID both identifies this react4xp object (aka. react4xpId), and crucially, points React to an HTML element (in the body param, during render or renderBody later) which is the target container for rendering the entry into. Phew.
If render or renderBody are called without an ID having been set yet, then a unique random ID will be generated on the fly. This of course implies that there will be no matching-ID element in body. In cases like this (or when there’s no body at all), an empty target element with a matching ID will be generated/inserted, to contain the React rendering. |
If the data object already has an ID, .setId(id) will overwrite it. If id is omitted/empty, .setId() just deletes any previous ID (which has the later effect of giving this a new, unique ID at the time of rendering).
| Name | Type | Description |
|---|---|---|
|
|
string |
Optional. ID of both the target HTML element and the data object itself. |
uniqueId
myComponent.uniqueId();
Enforces a unique ID, either by itself or after running .setId(). If the object already has an ID (react4xpId), a random string will be added to it. If not, the ID will just be the random string.
No parameters.
setJsxPath
myComponent.setJsxPath(jsxPath);
If you for some reason need to override the JsxPath that was set (or inferred from the component object) in the constructor.
| Name | Type | Description |
|---|---|---|
|
|
string |
New jsxPath to a different entry. |
The two rendering methods below perform specific rendering tasks independently, using the data object as set up with the setters and constructor (or setJsxPath).
| Most of these rendering methods will lock down the jsxPath and ID of the react4xp data object the first time one of them is run. After this, the setters will prevent these from being changed so that another conflicting rendering can’t be performed from the same data object. |
renderBody
const responseBody = myComponent.renderBody(options);
Similar to render above, but renderBody in itself only renders a static HTML output.
|
Does not render page contributions. Combine with a corresponding renderPageContributions call from the same data object, or the rendering will not be active in the browser. → See the custom flow syntax examples. |
renderBody renders based on the state of the data object reached at the time of rendering.
Just like render does, renderBody ensures that the output HTML will always contain a matching-ID target element for react-rendering/hydrating the entry into (in the browser). And if serverside rendering is switched on (that is, ssr is not false, or safe context-dependent rendering is enforced by adding request - see the summary), the target element will contain the static HTML rendering.
Parameters
renderBody() takes a single options object; all properties are optional. Other renderings are not affected, even from the same data object, so make sure a different rendering from the same data object uses the same mode.
| Name | Type | Description |
|---|---|---|
|
|
string |
Optional. Valid HTML to serve as container - same as |
|
|
boolean |
Optional. Switch between client-side and server-side rendering for this particular rendering. Defaults to |
|
|
boolean |
Optional. Whether to render the surrounding container element around the target element. |
|
|
Optional. Including this here (and in the corresponding |
Returns
Returns an HTML string ready to return as the body attribute in a response object from the controller.
The root of the returned HTML is always a surrounding container HTML that will have a matching-ID target element in it somewhere (an element matching the data object’s ID (react4xpId), either from the ID setter methods, or a generated ID if they haven’t been run). This surrounding structure is options.body, unchanged if that already contained a matching-ID element, or with a new target element generated and inserted at the end if it didn’t have one. If there is no options.body, the surrounding container is just a generated target element.
Inside that matching-ID element, there will be a serverside rendering of the entry (with the initial props from .setProps) if options.ssr is not false.
renderPageContributions
const outputPageContributions = myComponent.renderPageContributions(options);
Similar to render above, but only renders the page contributions needed to run and activate the react component in the browser:
-
references to the entry’s own asset,
-
dependency assets,
-
and the react-activating trigger call in the browser (
.renderor.hydrate, depending on thehydrate,ssrandrequestoptions).
Renders based on the state of the data object at the time of rendering.
|
Does not render any HTML. Run Also, unless you add the |
Parameters
renderPageContributions() takes a single options object; all properties are optional. Other renderings are not affected, even from the same data object, so make sure a different rendering from the same data object uses the same mode.
| Name | Type | Description |
|---|---|---|
|
|
Optional. Existing page contributions to add before the ones rendered here (within each section |
|
|
|
boolean |
Optional. When SSR is true, choose whether to hydrate. Defaults to |
|
|
boolean |
Optional. Switch between client-side and server-side rendering for this particular rendering. Defaults to |
|
|
|
Optional. URL type for assets: server-relative or absolute. Defaults to |
|
|
Optional. Including this here (and in the corresponding |
Returns
A regular page contributions object, ready to be used as the pageContributions attribute in an response object from the controller.
Includes everything the browser needs to activate (or client-side render) the react component: script tags with urls to auto-compiled assets for the entry and its dependencies, a client-side react4xp wrapper asset and an activating trigger call to the client wrapper. Urls point to react4xp’s own optimized asset services. Also included before this, are any input options.pageContributions.
With a serverside rendering (options.ssr is not false), the client will expect an existing target element with a pre-rendered entry in the response body, and call hydrate. If options.ssr is false, an empty target element is expected in the response body, and the rendering is left to the client with render.
Request and automated behavior
The "custom flow" (.renderBody in tandem with .renderPageContributions) is intended as a more low-level approach: less hand-holding, more control to the developer for cases where that’s needed.
However, lib-react4xp version 1.6.0 introduced support for a request option parameter for these methods as well. The main idea is that using request in both calls will now automate some behavior the same way as calling .render with request (see above).
Omitting request will still work the same way as before, leaving more to developers.
Custom flow with request
const body = myComponent.renderBody({
// ssr, etc
request
});
const pageContributions = myComponent.renderPageContributions({
// hydrate, ssr, etc
request
});
// ...etc, etc
This will act the same way as render used with a request: viewing context is detected, so inside Content Studio edit mode, hydrate and ssr are ignored and you always get SSR, and JS assets and the .hydrate call is held back so the react component isn’t activated inside Content Studio edit mode. And outside Content Studio edit mode, you get a fully active render.
As with render, error message details are held back in live view mode.
Custom flow without request:
const body = myComponent.renderBody({ /* ssr, etc */ });
const pageContributions = myComponent.renderPageContributions({ /* hydrate, ssr, etc */ });
// ...etc, etc
Contrary to when working with .render, omitting request from the custom flow does not enforce a max-safety rendering. Quite the opposite, removing request will remove all the "safety wheels", so this rendering mode needs a bit of attention to guarantee that everything works everywhere:
-
.renderBodywill takessrinto account in all contexts. What you set it to will take effect.This risks a missing/empty visualization inside Content Studio, since ssr: falsemakes sure no SSR will render a static placeholder. -
And
.renderPageContributionswill render all page contributions in all contexts, including JS dependency assets and thehydrate/renderbrowser-side calls.Best case scenario: this might make a client-side rendered entry visible in Content Studio too. Worst case, it risks intervening with Content Studio’s UX, or even break its functionality, depending on the code used/imported by the entry.
Custom flow examples
Custom flow usage in is demonstrated here.