Skip to main content

📦 @livepreso/react-plugin-textfield

Installing​

npm install @livepreso/react-plugin-textfield

Components​

TextField​

Unmanaged rich text editor. The parent component is responsible for providing the value and handling changes via onChange.

import React, { useState } from "react";
import { TextField } from "@livepreso/react-plugin-textfield";

export default function () {
const [value, setValue] = useState("<p>Hello world</p>");
return (
<TextField
value={value}
onChange={setValue}
textStyles={[
{ block: 0, title: "Body" },
{ block: 1, title: "Heading 1" },
]}
/>
);
}

Props:

Prop NameTypeDescription
valueStringHTML string value for the editor.
onChangeFunctionCalled with the updated HTML string on each change.
tagStringConstrains the editor to a specific HTML block type (p, h1–h6). See tag.
isReadOnlyBooleanDisables editing. Defaults to false.
classNameStringAdditional CSS class applied to the editor wrapper.
textStylesArrayText style options for the heading selector. See textStyles.
colorsArrayColour swatches for the text colour picker. See colors.
toolbarConfigArrayOrdered list of toolbar group IDs to display. Defaults to DEFAULT_TOOLBAR_CONFIG. See Toolbar.
tableToolbarConfigArrayOrdered list of table toolbar group IDs. Defaults to DEFAULT_TABLE_TOOLBAR_CONFIG. See Toolbar.
tokensArrayAvailable tokens for insertion. See tokens.
tokenConfigObjectAdditional options passed to the token extension. See tokens.
autofocusBooleanFocuses the editor on mount. Defaults to false.
extensionsObjectCustom Tiptap extensions keyed by name, merged with those derived from the toolbar config.
isScrollableBooleanScrolls content that overflows the field instead of clipping it. See Scrolling.
maskSelectorStringOverrides the container the toolbars are kept inside. Defaults to the text field itself.
disableSpellcheckBooleanDisables browser spellcheck. Defaults to false.
childrenNodeRendered to an HTML string and used as the value if value is not provided.

ManagedTextField​

Bridge managed rich text editor. Content is stored in CMS Vals (editable in PresoManager) when isCompany is set, and in the preso context (editable by the preso owner in prep mode) when isPrep is set. Both can be set simultaneously — in that case, the preso context value takes precedence during prep, falling back to the company-managed value when no per-preso edit exists.

At least one of isPrep or isCompany must be set, unless isReadOnly is true.

import React from "react";
import { ManagedTextField } from "@livepreso/react-plugin-textfield";

export default function () {
return (
<ManagedTextField id="body_text" isCompany={true} isPrep={true}>
<p>Default text content.</p>
</ManagedTextField>
);
}
info

When isCompany is set, the id must be registered in the slide's editables list in project.yaml. See Project file — editables.

Props:

Prop NameTypeDescription
idStringCMS Vals key for company-managed content, and default key for prep editable storage.
prepIdStringOverride key for prep editable storage. Defaults to id.
tagStringConstrains the editor to a specific HTML block type (p, h1–h6). See tag.
isCompanyBooleanEnables company-managed editing in PresoManager. The id must be registered in project.yaml editables.
isPrepBooleanEnables per-preso editing in prep mode. Changes are saved to the preso context.
isReadOnlyBooleanDisables editing. Defaults to false.
scopeString"instance" (the default) keeps one value per placement of the slide. "deck" shares one value with every slide and placement using this id.
classNameStringAdditional CSS class applied to the editor wrapper.
textStylesArrayText style options for the heading selector. See textStyles.
colorsArrayColour swatches for the text colour picker. See colors.
toolbarConfigArrayOrdered list of toolbar group IDs to display. Defaults to DEFAULT_TOOLBAR_CONFIG. See Toolbar.
tableToolbarConfigArrayOrdered list of table toolbar group IDs. Defaults to DEFAULT_TABLE_TOOLBAR_CONFIG. See Toolbar.
tokensArrayAvailable tokens for insertion. See tokens.
tokenConfigObjectAdditional options passed to the token extension. See tokens.
autofocusBooleanFocuses the editor on mount. Defaults to false.
extensionsObjectCustom Tiptap extensions keyed by name, merged with those derived from the toolbar config.
isScrollableBooleanScrolls content that overflows the field instead of clipping it. See Scrolling.
maskSelectorStringOverrides the container the toolbars are kept inside. Defaults to the text field itself.
disableSpellcheckBooleanDisables browser spellcheck. Defaults to false.
childrenNodeRendered to an HTML string and used as the default value.

Scrolling​

A field clips content that overflows its box. Pass isScrollable to have it scroll that overflow instead.

The field needs a height to overflow. isScrollable only does something once the field has a definite height from somewhere — a fixed height, or height: 100% inside a parent that constrains it. A field sized to its content never overflows and so never scrolls.

className is applied to the field element itself, so that is where the height goes:

<ManagedTextField id="body_text" isCompany={true} className={style.field} isScrollable>
<p>Default text content.</p>
</ManagedTextField>
.field {
// Gives the field something to overflow. Without a height it grows with its
// content and `isScrollable` does nothing.
height: 240px;
}

height: 100% works in place of a fixed height wherever the parent constrains it — to fill what's left of a flex column, give that parent flex: 1 1 auto; min-height: 0, the min-height: 0 being what lets it shrink below its content.

Don't put the overflow on a wrapper instead. The toolbars resolve both their anchor clipping and their scroll listener against the field element itself; adding a scrolling wrapper will break the toolbar tracking, allowing them to drift out of position as you scroll. A wrapper with overflow: hidden is still fine for clipping a border radius around the field.

Screenshots always clip, never scroll, isScrollable or not: a scrollbar in a rendered PDF would cut content silently, and capturing a scrollable area needs the explicit multi-page screenshot configuration described in Preso modes.

Toolbar​

The toolbar is configured via the toolbarConfig and tableToolbarConfig props, which accept ordered arrays of group ID constants. Groups are rendered left to right in the order they appear in the array.

Toolbar config constants are available from @livepreso/react-plugin-textfield/constants.

import React from "react";
import { ManagedTextField } from "@livepreso/react-plugin-textfield";
import { SIMPLE_TOOLBAR_CONFIG } from "@livepreso/react-plugin-textfield/constants";

export default function () {
return (
<ManagedTextField id="body_text" isCompany={true} toolbarConfig={SIMPLE_TOOLBAR_CONFIG}>
<p>Default text.</p>
</ManagedTextField>
);
}

Pre-built configurations​

ConstantDescription
DEFAULT_TOOLBAR_CONFIGFull set of primary toolbar groups. This is the default.
SIMPLE_TOOLBAR_CONFIGUndo/redo, text style, tokens, and clear formatting.
MINIMAL_TOOLBAR_CONFIGUndo/redo only.
COMPLETE_TOOLBAR_CONFIGAlias for DEFAULT_TOOLBAR_CONFIG.
DEFAULT_TABLE_TOOLBAR_CONFIGFull set of table toolbar groups. This is the default.
SIMPLE_TABLE_TOOLBAR_CONFIGDelete table, column and row operations only.
COMPLETE_TABLE_TOOLBAR_CONFIGAlias for DEFAULT_TABLE_TOOLBAR_CONFIG.

Toolbar groups​

Primary toolbar groups (toolbarConfig):

ConstantGroup IDContents
UNDO_REDO"undo"Undo, redo
BLOCK"block"Heading/block type selector (requires textStyles)
TEXT_STYLE"text-style"Bold, italic, underline, text colour, superscript, subscript
ALIGNMENT"alignment"Left, centre, right, justify
LINK"link"Insert/edit link, remove link
TOKEN"token"Insert token (only visible when tokens is non-empty)
LIST"list"Bullet list, ordered list
TABLE"table"Insert table
CLEAR_FORMATTING"clear-formatting"Clear all formatting

Table toolbar groups (tableToolbarConfig):

ConstantGroup IDScopeContents
TABLE_SIZE"tableSize"Table-wideFull width, equal column widths
DELETE_TABLE"deleteTable"Table-wideDelete table
COLUMN"column"Cell menuAdd column left/right, remove column
ROW"row"Cell menuAdd row above/below, remove row
CELL"cell"Cell menuMerge cells, split cells, cell background colour, cell vertical alignment

Table-wide groups appear in a toolbar below the focused table. Cell menu groups appear in a contextual menu within the focused cell.

textStyles​

The textStyles prop accepts an array of style objects that populate the heading/block type selector in the toolbar (BLOCK group). Each object has:

KeyTypeDescription
blockNumberThe block level. 0 = paragraph, 1-6 = heading level.
titleStringLabel shown in the toolbar dropdown.
const textStyles = [
{ block: 0, title: "Body" },
{ block: 1, title: "Title" },
{ block: 2, title: "Heading" },
{ block: 3, title: "Subheading" },
];
info

The BLOCK group must be included in toolbarConfig for the selector to appear.

colors​

The colors prop accepts an array of hex colour strings used to populate the swatches in the text colour picker.

const colors = ["#000000", "#ffffff", "#cc0000", "#1a73e8"];
info

The TEXT_STYLE group must be included in toolbarConfig for the colour picker to appear.

tokens​

Tokens are dynamic named values that can be inserted into the field by the user. They are displayed as inline nodes that render their value at runtime.

The tokens prop accepts an array of token objects:

KeyTypeDescription
idStringUnique identifier for the token.
labelStringLabel shown in the token picker and as a placeholder in editable mode.
descriptionStringOptional description shown in the token picker.
renderFunctionReturns the token's rendered string value.
optionsObjectOptional per-token configuration (e.g. { burstOnCreate: true }).
const tokens = [
{
id: "customer_name",
label: "Customer name",
description: "The customer's full name",
render: () => context.customer.name,
},
];
info

An array must be supplied to the tokens prop, as well as the TOKEN group included in toolbarConfig for the insert button to appear. The Token extension is always registered when tokens is non-empty, so existing token nodes render correctly regardless of whether the insert button is shown.

tokenConfig​

The tokenConfig prop accepts additional options passed to the Token extension at the field level:

KeyTypeDescription
burstOnCreateBooleanWhen true, the token node is immediately replaced with its rendered text value on insertion. Useful in modes where tokens should not persist as interactive nodes.

tag​

The tag prop constrains the editor's document type to a specific HTML block element. When set, users cannot switch between block types. Supported values: p, h1-h6. Defaults to div when omitted.

// Editor can only contain paragraph content
<TextField tag="p" ... />

// Editor locked to h2 content
<TextField tag="h2" ... />
note

Text format switching (ie. block types) is only available when the editable tag is a div.