@charlietango/react-umbraco
v0.3.0
Published
React components for working with Umbraco Headless
Downloads
30
Readme
react-umbraco
A collection of React components for working with the Umbraco Content Delivery API.
Install
Install the @charlietango/react-umbraco
package with your package manager of
choice.
npm install @charlietango/react-umbraco
<UmbracoRichText>
Takes the rich text property from the Umbraco Content Delivery API and renders it with React.
Props
element
: The rich text property from the Umbraco Content Delivery API.renderBlock
: Render a specific block type.renderNode
: Overwrite the default rendering of a node. Returnundefined
to render the default node. Returnnull
to skip rendering the node.htmlAttributes
: Default attributes to set on the defined HTML elements. These will be used, unless the element already has the attribute set. The only exception is theclassName
attribute, which will be merged with the default value.
When passing the renderBlock
and renderNode
props, consider making them
static functions (move them outside the consuming component) to avoid
unnecessary re-renders.
import {
UmbracoRichText,
RenderBlockContext,
RenderNodeContext,
} from "@charlietango/react-umbraco";
import Image from "next/image";
import Link from "next/link";
function renderNode({ tag, children, attributes }: RenderNodeContext) {
switch (tag) {
case "a":
return <Link {...attributes}>{children}</Link>;
case "p":
return (
<p className="text-lg" {...attributes}>
{children}
</p>
);
default:
// Return `undefined` to render the default HTML node
return undefined;
}
}
function renderBlock({ content }: RenderBlockContext) {
switch (content?.contentType) {
// Switch over your Umbraco document types that can be rendered in the Rich Text blocks
case "imageBlock":
return <Image {...content.properties} />;
default:
return null;
}
}
function RichText({ data }) {
return (
<UmbracoRichText
element={data.richText}
renderNode={renderNode}
renderBlock={renderBlock}
htmlAttributes={{ p: "mb-4" }}
/>
);
}
Blocks
You can augment the renderBlock
method with the generated OpenAPI types from
Umbraco Content Delivery API. That way you can correctly filter the blocks you
are rendering, based on the contentType
, and get the associated properties
.
Create types/react-umbraco.d.ts
, and augment the UmbracoBlockItemModel
interface with your applications definition for ApiBlockItemModel
.
To generate the types, you'll want to use the Delivery Api Extensions package, alongside a tool to generate the types from the OpenAPI schema, like openapi-typescript.
types/react-umbraco.d.ts
import { components } from "@/openapi/umbraco";
// Define the intermediate interface
type ApiBlockItemModel = components["schemas"]["ApiBlockItemModel"];
declare module "@charlietango/react-umbraco" {
interface UmbracoBlockItemModel extends ApiBlockItemModel {}
}
richTextToPlainText
A utility function to convert an Umbraco RichText element to plain text. This can be useful for generating meta descriptions or other text-based properties.
Parameters
data
(RichTextElementModel
): The rich text element to be converted.options
(Options
, optional): An object to specify additional options.firstParagraph
(boolean
, optional): Iftrue
, only the first paragraph with text content will be returned.maxLength
(number
, optional): The maximum length of the returned text. If the text exceeds this length, it will be truncated to the nearest word and an ellipsis will be added.ignoreTags
(Array<string>
, optional): An array of tags to be ignored during the conversion.
Returns
string
: The plain text representation of the rich text element.
Example
import { richTextToPlainText } from "@charlietango/react-umbraco";
const plainText = richTextToPlainText(richTextData);
// Just the first paragraph
const firstParagraph = richTextToPlainText(richTextData, {
firstParagraph: true,
});
// Just the first 100 characters, truncated at the nearest word with an ellipsis
const first100Characters = richTextToPlainText(richTextData, {
maxLength: 100,
});
// Ignore certain tags, skipping their content
const ignoreTags = richTextToPlainText(richTextData, {
ignoreTags: ["h1", "h2", "ol", "figure"],
});