@remoteoss/remote-flows

  !Coverage

> 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
- Custom Field Components
- Available Flows
- Authentication
- Styling Options
- Using Default Styles
- Theme Customization
- Custom CSS
- Advanced Usage
- Example
- Contributing
- Internals

Installation

``sh
npm install @remoteoss/remote-flows
`

Quick Start

`tsx
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 (
components={defaultComponents}
auth={fetchToken}
environment='partners'
>
console.log(data)} />

);
}
`

Components API

$3

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

| Prop | Type | Required | Deprecated | Description |
| --------------- | --------------------------------------------------------------------------------------------- | -------- | ---------- | --------------------------------------------------------------------------- |
| auth | () => Promise<{ accessToken: string, expiresIn: number }> | Yes | - | Function to fetch authentication token |
| 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 } | 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 |

#### Error Boundary

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

`tsx
components={defaultComponents}
auth={fetchToken}
errorBoundary={{
useParentErrorBoundary: false,
fallback: (error) => (



),
}}
>
{/ Your flows /}

`

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

$3

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.

$3

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

Styling Options

$3

Import the CSS file in your application:

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

$3

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

`

| 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. |

$3

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

Example: Customize the Cost Calculator layout:

`css
.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:

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

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

return (


submitCostCalculator(data))}>
{/ Your custom form implementation /}

);
}


`

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.

`

``