Polaris Rich Text Field

The RichTextField component provides a streamlined way to edit Shopify rich text metafields within your embedded app.

⚠️ This is not a general-purpose rich text editor. It is specifically designed for editing Shopify metafields of type rich_text_field, not for generating arbitrary HTML.

Since version 2, this library uses Polaris Web Components. Please note that Polaris Web Components are not yet officially released, so you may encounter breaking changes. If you are still using the older Polaris React, consider sticking with version 1.

---

📦 Installation

npm i @maestrooo/rich-text-field

This library uses Slate under the hood (which is the same library that Shopify uses for their own rich text field editor, ensuring we get a consistent experience).

This library relies on Polaris Web Components under the hood.
To use it correctly, make sure you load Polaris Web Components following the official instructions.

---

🛠️ Usage

Import the component and use it in your app:

import { RichTextField } from "@maestrooo/rich-text-field";

export default function MyComponent() {
  return (
    <RichTextField 
      name="description"
      value={metafield.jsonValue} 
      onChange={(newValue) => doSomething(newValue)} 
    />
  );
}

---

🧾 Props

Prop	Type	Required	Description
value	object | string | null	✅	The current metafield value. Use metafield.jsonValue or a stringified value of the JSON.
onChange	(event: ChangeEvent) => void	❌	Callback triggered whenever the content changes. Returns a change event. You can retrieve the value using event.currentTarget.value
onInput	(event: ChangeEvent) => void	❌	Callback triggered whenever the content changes. Returns a change event. You can retrieve the value using event.currentTarget.value
onBlur	(event: FocusEvent) => void	❌	Callback triggered when the field is blurred
onFocus	(event: FocusEvent) => void	❌	Callback triggered when the field is focused
toolbarOptions	Array<'formatting' | 'bold' | 'italic' | 'link' | 'ordered-list' | 'unordered-list'>	❌	Controls which tools are available in the toolbar.
label	string	❌	Optional label for the field.
details	string	❌	Optional details text displayed below the field.
placeholder	string	❌	Placeholder text shown when the field is empty.
error	string	❌	Optional error message displayed below the field.

As of today, onChange and onInput behave the same way: the onChange event is triggered on every keystroke. This is a limitation of the Slate library, which does not distinguish between the two.

---

⚠️ Notes

• You can use metafield.jsonValue or metafield.value as the value.
• When the value is empty, the library will return an empty string (``) and not an empty object. This happens because Shopify expects an empty string to clear a rich text metafield.