@remoteoss/remote-flows

Note: This badge reflects the latest published version. Check npm for current version information.

A React library that provides components for Remote's embedded solution, enabling seamless integration of Remote's employment flows into your application.

Table of Contents

• Installation
• Quick Start
• Components API
  • RemoteFlows
    • Error Boundary
    • HTML Transformation
  • Custom Field Components
• Available Flows
• Authentication
• Styling Options
  • Using Default Styles
  • Theme Customization
  • Custom CSS
• Advanced Usage
• Example
• Contributing
• Internals

Installation

npm install @remoteoss/remote-flows

Quick Start

import { RemoteFlows, CostCalculator } from '@remoteoss/remote-flows';
import { defaultComponents } from '@remoteoss/remote-flows/default-components';
import '@remoteoss/remote-flows/styles.css';

function App() {
  const fetchToken = async () => {
    const response = await fetch('/api/auth/token');
    return response.json();
  };

  return (
    <RemoteFlows
      components={defaultComponents}
      auth={fetchToken}
      environment='partners'
    >
      <CostCalculator onSuccess={(data) => console.log(data)} />
    </RemoteFlows>
  );
}

Components API

RemoteFlows

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
transformHtmlToComponents	(htmlContent: string) => ReactNode	No	-	Optional function to transform HTML strings into React components. Useful for customizing HTML content rendering

Error Boundary

The errorBoundary prop controls how the SDK handles runtime errors to prevent crashes in your host application.

<RemoteFlows
  components={defaultComponents}
  auth={fetchToken}
  errorBoundary={{
    useParentErrorBoundary: false,
    fallback: (error) => (
      <div style={{ padding: '20px', textAlign: 'center' }}>
        <h2>Something Went Wrong</h2>
        <p>{error.message}</p>
        <button onClick={() => window.location.reload()}>Reload Page</button>
      </div>
    ),
  }}
>
  {/* Your flows */}
</RemoteFlows>

Options:

• useParentErrorBoundary (boolean, default: false): If true, errors are re-thrown to your parent error boundary. If false, the SDK shows a fallback UI to prevent crashes.
• fallback (ReactNode | function, optional): Custom UI to display when an error occurs. Only used when useParentErrorBoundary is false. Can be a React element or a function that receives the error object.

Behavior:

• When useParentErrorBoundary: true → Errors propagate to your application's error boundary
• 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.

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 - Client-side HTML sanitization
• 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.

For detailed documentation on component customization including step-level and field-specific overrides, see the Component Customization Guide.

Available Flows

Each flow handles a specific Remote employment operation. For detailed API documentation, see the individual flow READMEs:

• Cost Calculator - Calculate employment costs for different countries
• Onboarding - Onboard new employees
• Contract Amendment - Modify existing employment contracts
• Termination - Handle employee terminations

Authentication

You need to implement a server endpoint to securely handle authentication with Remote. This prevents exposing client credentials in your frontend code.

Your server should:

1. Store your client credentials securely
2. Implement an endpoint that exchanges these credentials for an access token
3. Return access_token and expires_in to the frontend application

For a complete implementation, check our example server implementation.

API Gateway Endpoints

• Development/Testing: https://gateway.partners.remote-sandbox.com
• Production: https://gateway.remote.com/

Styling Options

Using Default Styles

Import the CSS file in your application:

@import '@remoteoss/remote-flows/styles.css';

Theme Customization

<RemoteFlows
  theme={{
    spacing: '0.25rem',
    borderRadius: '0px',
    colors: {
      primaryBackground: '#ffffff',
      primaryForeground: '#364452',
      accentBackground: '#e3e9ef',
      accentForeground: '#0f1419',
      danger: '#d92020',
      borderInput: '#cccccc',
    },
  }}
>
  {/* Your components */}
</RemoteFlows>

Token	Description
colors.borderInput	Border color for input fields.
colors.primaryBackground	Background used for the popover options
colors.primaryForeground	Color text for the input and options
colors.accentBackground	Used in the option selected and hover.
colors.accentForeground	Color text for the select options
colors.danger	Red color used for danger states.
spacing	Consistent scale for whitespace (margin, padding, gap).
borderRadius	The main border radius value (default: 0.625rem). This is the foundation for all other radius values.
font.fontSizeBase	The main font size value (default: 1rem). Controls the base text size of the component.

Custom CSS

All components expose CSS classes prefixed with RemoteFlows__ for targeted styling:

Example: Customize the Cost Calculator layout:

.RemoteFlows__CostCalculatorForm {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 1rem;
}

.RemoteFlows__SelectField__Item__country {
  grid-column: span 2;
}

.RemoteFlows__CostCalculatorForm .RemoteFlows__Button {
  grid-column: span 2;
}

Advanced Usage

For complete control over rendering, use our hooks directly. They handle the business logic while you control the UI:

import { useCostCalculator } from '@remoteoss/remote-flows';

function CustomCostCalculator() {
  const {
    onSubmit: submitCostCalculator,
    fields, // Field definitions from json-schema-form
    validationSchema,
  } = useCostCalculator();

  return (
    <form onSubmit={handleSubmit((data) => submitCostCalculator(data))}>
      {/* Your custom form implementation */}
    </form>
  );
}

Learn more about field definitions in the json-schema-form documentation.

Example

For a complete implementation example, see our example application.

Contributing

We welcome contributions! If you're working on this package:

• See DEVELOPMENT.md for development setup, testing, and bundle size management
• Check out our example app to test changes locally
• Ensure bundle size stays within limits before submitting PRs

Internals

We have created an entry point in the package @remoteoss/remote-flows/internals

This entry endpoint exports internals utils and shadcn components to avoid duplicating these on the example folder.

We don't guarantee semver compatiblity if you used them in your project.