Skip to content

docs(transformHTMLToComponents) - Add some docs #994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gabrielseco wants to merge 3 commits into
base: add-example-and-expose-prop
Choose a base branch
from
Open

docs(transformHTMLToComponents) - Add some docs #994

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1aeb2e1
add new prop to table
gabrielseco May 4, 2026
9961b5d
add readme
gabrielseco May 4, 2026
70f31e1
update readme
gabrielseco May 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 83 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ A React library that provides components for Remote's embedded solution, enablin
- [Quick Start](#quick-start)
- [Components API](#components-api)
- [RemoteFlows](#remoteflows)
- [Error Boundary](#error-boundary)
- [HTML Transformation](#html-transformation)
- [Custom Field Components](#custom-field-components)
- [Available Flows](#available-flows)
- [Authentication](#authentication)
Expand Down Expand Up @@ -61,16 +63,17 @@ function App() {

The `RemoteFlows` component serves as a provider for authentication and theming.

| Prop | Type | Required | Deprecated | Description |
| --------------- | --------------------------------------------------------------------------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| `auth` | `() => Promise<{ accessToken: string, expiresIn: number }>` | No | - | Function to fetch authentication token. Optional when using cookie-based authentication via `credentials` prop |
| `environment` | `'partners' \| 'production' \| 'sandbox' \| 'staging'` | No | - | Environment to use for API calls (defaults to production) |
| `theme` | `ThemeOptions` | No | - | Custom theme configuration |
| `components` | `Components` | No | - | Custom field components for form rendering |
| `proxy` | `{ url: string, headers?: Record<string, string> }` | No | - | Configuration for API request proxy with optional headers |
| `errorBoundary` | `{ useParentErrorBoundary?: boolean, fallback?: ReactNode \| ((error: Error) => ReactNode) }` | No | - | Error boundary configuration to prevent crashes and show custom fallback UI |
| `debug` | boolean | No | - | useful to see telemetry debugging in console |
| `credentials` | `'include' \| 'same-origin'` | No | - | Credentials mode for fetch requests. Use `'include'` for cookie-based authentication without bearer tokens |
| Prop | Type | Required | Deprecated | Description |
| --------------------------- | --------------------------------------------------------------------------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
| `auth` | `() => Promise<{ accessToken: string, expiresIn: number }>` | No | - | Function to fetch authentication token. Optional when using cookie-based authentication via `credentials` prop |
| `environment` | `'partners' \| 'production' \| 'sandbox' \| 'staging'` | No | - | Environment to use for API calls (defaults to production) |
| `theme` | `ThemeOptions` | No | - | Custom theme configuration |
| `components` | `Components` | No | - | Custom field components for form rendering |
| `proxy` | `{ url: string, headers?: Record<string, string> }` | No | - | Configuration for API request proxy with optional headers |
| `errorBoundary` | `{ useParentErrorBoundary?: boolean, fallback?: ReactNode \| ((error: Error) => ReactNode) }` | No | - | Error boundary configuration to prevent crashes and show custom fallback UI |
| `debug` | boolean | No | - | useful to see telemetry debugging in console |
| `credentials` | `'include' \| 'same-origin'` | No | - | Credentials mode for fetch requests. Use `'include'` for cookie-based authentication without bearer tokens |
| `transformHtmlToComponents` | `(htmlContent: string) => ReactNode` | No | - | Optional function to transform HTML strings into React components. Useful for customizing HTML content rendering |

#### Error Boundary

Expand Down Expand Up @@ -106,6 +109,76 @@ The `errorBoundary` prop controls how the SDK handles runtime errors to prevent
- When `useParentErrorBoundary: false` without `fallback` → Shows default error message: "Something went wrong in RemoteFlows. Please refresh the page."
- When `useParentErrorBoundary: false` with `fallback` → Shows your custom fallback UI

#### HTML Transformation

The `transformHtmlToComponents` prop allows you to transform HTML strings from API responses into custom React components. This is useful for replacing generic HTML patterns with your own component library.

```tsx
import parse, {
domToReact,
HTMLReactParserOptions,
Element,
} from 'html-react-parser';
import DOMPurify from 'dompurify';

function transformHtmlToComponents(htmlContent: string) {
// 1. Sanitize HTML first (IMPORTANT for security)
const clean = DOMPurify.sanitize(htmlContent);

// 2. Define transformation options
const options: HTMLReactParserOptions = {
replace: (domNode) => {
// Transform <details data-component="Accordion"> to custom Accordion
if (domNode.type === 'tag' && domNode.name === 'details') {
const element = domNode as Element;
if (element.attribs?.['data-component'] === 'Accordion') {
// Find the summary tag
const summaryNode = element.children?.find(
(child) => child.type === 'tag' && child.name === 'summary',
);

// Extract content
const summary = summaryNode
? domToReact(summaryNode.children, options)
: 'Details';
const content = element.children?.filter(
(child) => !(child.type === 'tag' && child.name === 'summary'),
);

return (
<CustomAccordion summary={summary}>
{domToReact(content || [], options)}
</CustomAccordion>
);
}
}
},
};

// 3. Parse and transform
return parse(clean, options);
}

<RemoteFlows
components={defaultComponents}
auth={fetchToken}
transformHtmlToComponents={transformHtmlToComponents}
>
{/* Your flows */}
</RemoteFlows>;
```

**Security Notice:** The function receives **unsanitized HTML**. You are responsible for sanitizing untrusted content before rendering. Consider using:

- [`DOMPurify`](https://github.com/cure53/DOMPurify) - Client-side HTML sanitization
- [`sanitize-html`](https://github.com/apostrophecms/sanitize-html) - Server-side HTML sanitization

**Common Use Cases:**

- Replace `<details>` elements with custom accordion components
- Transform links with custom styling or tracking
- Inject custom components for specific HTML patterns marked with `data-component` attributes

### Custom Field Components

You can customize form field components to match your application's design system.
Expand Down
Loading