Remote Flows SDK

Overview

Remote Flows is an SDK designed for partners to embed Remote's onboarding and employment flows directly into their platforms. It simplifies the process of embedding complex flows — such as cost estimation, offboarding and contract amendments — by handling all the heavy lifting behind the scenes.

By removing API orchestration, form schema parsing, validation, and state management, Remote Flows enables teams to move faster, reduce integration effort, and build a more reliable experience for end users.

Getting Started

Prerequisites

Before getting started with SDK installation and usage, ensure your project meets the following requirements:

React 18 or higher installed on your system
A valid Remote API key

Find Remote Flow's source code, getting started steps, and examples in detail on our GitHub page.

Installation

To get started, install the package via your preferred package manager.

npm install @remoteoss/remote-flows
# or
yarn add @remoteoss/remote-flows

Example usage

Here's a simple example of rendering the cost calculator using the Remote Flows SDK:

import {
  CostCalculatorFlow,
  RemoteFlows,
  CostCalculatorForm,
  CostCalculatorSubmitButton,
  CostCalculatorResetButton,
} from '@remoteoss/remote-flows';

import './App.css';

const fetchToken = () => {
  return fetch('/api/token')
    .then((res) => res.json())
    .then((data) => ({
      accessToken: data.access_token,
      expiresIn: data.expires_in,
    }))
    .catch((error) => {
      console.error({ error });
      throw error;
    });
};

export function Demo() {
  return (
    <RemoteFlows auth={() => fetchToken()}>
      <CostCalculatorFlow
        estimationOptions={{
          title: 'Cost Calculator',
          includeBenefits: true,
          includeCostBreakdowns: true,
        }}
        render={(props) => {
          if (props.isLoading) {
            return <div>Loading...</div>;
          }

          return (
            <>
              <CostCalculatorForm />
              <div>
                <CostCalculatorSubmitButton>
                  Get estimate
                </CostCalculatorSubmitButton>
                <CostCalculatorResetButton>Reset</CostCalculatorResetButton>
              </div>
            </>
          );
        }}
      />
    </RemoteFlows>
  );
}

In this code, there are three main components:

fetchToken: This function makes an API call to /api/token and returns the access token with expiry in response.
demo: This function sets up authentication using the RemoteFlows provider component. Its primary function is to configure the calculator with options for title, benefits, and cost breakdown.
render: Inside the demo, render handles UI of the calculator.

This example shows how quickly you can implement a complex flow with minimal code.

Components

The Remote Flows SDK provides a set of prebuilt, opinionated React components that handle everything from schema fetching to form rendering, validation, and multi-step state management.

These components are designed to offer a fast path to integration with sensible defaults for layout, labeling, and behavior. All components are styled using Tailwind CSS and can be fully customized using utility classes and submission logic.

Custom field components

The Remote Flows SDK supports customizing how individual form fields are rendered using the components prop. This allows you to override the default UI with your own field implementations while retaining full integration with the form's internal logic and validation.

Custom components are wrapped in Controller from React Hook Form, which means they receive:

field: React Hook From's registration props (e.g. value, onChange, onBlur)
fieldState: The current state of the field (e.g. error, isTouched)
fieldData: Metadata from the JSON schema (e.g. label, options, field type)

⚠️ It is important to bind field to your input element to ensure proper form control and validation.

<RemoteFlows
  components={{
    number: ({ field, fieldState, fieldData }) => (
      <div>
        <label>{fieldData.label}</label>
        <input {...field} />
        {fieldState.error && (
          <span className="text-red-500">{fieldState.error.message}</span>
        )}
      </div>
    ),
    select: ({ field, fieldState, fieldData }) => (
      <>
        <select {...field} onChange={(ev) => field.onChange(ev.target.value)}>
          {fieldData?.options?.map((option) => (
            <option key={option.value} value={option.value}>
              {option.label}
            </option>
          ))}
        </select>
        {fieldState.error && (
          <span className="text-red-500">{fieldState.error.message}</span>
        )}
      </>
    ),
  }}
  auth={fetchToken}
>
  {/* Your form components */}
</RemoteFlows>

You can override field rendering for the following types:

text: Standard single-line text inout. Used for free-form answers such as names, titles, or short descriptions.
textarea: Multi-line text input. Ideal for comments, notes, or longer content.
number: Numeric input field. Supports integers or decimals depending on schema configuration.
money: A formatted currency input. Typically used for salary, compensation, or budget fields.
select: A dropdown field with predefined options. Useful for country selection, roles, categories, etc.
radio: A group of radio buttons for selecting a single value from a list. Best for mutually exclusive choices.
checkbox: A single-select inout. Used for toggles, confirmations, or opt-in selections.
file: A file upload input field. Supports attaching documents such as contracts, IDs, etc.
date: A calendar-based data picker. Commonly used for selecting start dates, birth dates, deadlines, etc.
fieldset: A group of related fields bundled under a shared context or title. Useful for logically grouping inputs like address or contact information.

This customization layer allows partners to fully control form behavior, validation messages, and presentation without rebuilding the flow logic from scratch.

Hooks

For partners who want full control over UI and styling, the SDK provides composable React hooks that power all components behind the scenes. These hooks give access to:

Schema-driver field configuration
Type-safe submission functions
Field-level visibility and validation logic

Hooks follow the same internal logic as the components but expose it in a way that can be integrated into your own custom UI.

Below is an example of what the customization looks like using the useCostCalculator component.

import { useCostCalculator } from "@remoteoss/remote-flows"

function MyCustomCostCalculator() {
  const {
    onSubmit: submitCostCalculator,
    fields,
    validationSchema,
  } = useCostCalculator();

  function handleOnSubmit(formValues) {
    submitCostCalculator(formValues);
  }

  return (
    <form onSubmit={handleOnSubmit}>
      {fields.map((field) => {
        if (!field.isVisible || field.deprecated) return null;

        if (field.type === 'text') {
          return <input {...field} />;
        }

        if (field.type === 'select') {
          return (
            <select {...field}>
              {field.options.map((option) => (
                <option value={option.value}>{option.label}</option>
              ))}
            </select>
          );
        }

        // handle other field types...
      })}
    </form>
  );
}

This SDK takes care of:

Fetching and handling multi-step JSON schemas
Rendering form fields using json-schema-form
Validating and submitting payloads
Managing loading and error states
Keeping interactions type-safe with auto-generated types