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.

• 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

For maintainers and contributors: See ARCHITECTURE.md for architectural patterns, design philosophy, and decision-making framework.

npm install @remoteoss/remote-flows

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>
  );
}

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

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

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

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.

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

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.

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

Import the CSS file in your application:

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

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

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;
}

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.

For a complete implementation example, see our example application.

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

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.