---
title: "Onboarding SDK examples"
url: "https://platformdocs.coinme.com/#/docs/onboarding-sdk-examples"
markdown: "https://platformdocs.coinme.com/docs/onboarding-sdk-examples.md"
summary: "Every way to put the Onboarding SDK on a page, each as the code you would write and the form it produces. The forms are live: the secure SSN field is the real vault field, and submits are simulated, so nothing reaches Coinme."
surface: "caas"
platform: "web"
package: "@coinme-security/onboarding-sdk-react"
version: "1.7.1"
peerDependencies: {"react":">=18","react-dom":">=18"}
---

# Onboarding SDK examples

Every way to put the Onboarding SDK on a page, each as the code you would write and the form it produces. The forms are live: the secure SSN field is the real vault field, and submits are simulated, so nothing reaches Coinme.

The [JavaScript & React guide](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) explains every prop these examples use.

<a id="drop-in-form"></a>

## Drop-in form

The quickest integration. `CustomerOnboardingForm` renders every field the endpoint needs, the SSN included, validates as the customer types, and calls you back with the new `customerId` and the phone number the customer onboarded with. Styling is pass-through: the class names in `fieldProps` and `classNames` are yours, and the CSS tab is all the styling on this page.

Onboarding is complete only once that phone is verified, so `onSuccess` moves the customer on to the SDK's [phone verification step](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#phone-verification). The forms on this page stop at the onboarding submit.

```tsx
import { CustomerOnboardingForm } from '@coinme-security/onboarding-sdk-react';

const FIELD_PROPS = {
  email: { className: 'input', placeholder: 'you@example.com' },
  firstName: { className: 'input' },
  middleName: { className: 'input' },
  lastName: { className: 'input' },
  addressLine1: { className: 'input' },
  addressLine2: { className: 'input' },
  city: { className: 'input' },
  state: { className: 'input' },
  postalCode: { className: 'input' },
  phoneNumber: { className: 'input' },
  dateOfBirth: { className: 'input' },
  ssn: {
    placeholder: '123-45-6789',
    css: { fontSize: '16px', fontFamily: 'Inter, sans-serif', color: '#0b1220' },
    containerProps: { className: 'input' },
  },
};

const CLASS_NAMES = {
  form: 'form',
  row: 'field',
  label: 'field-label',
  control: 'field-control',
  fieldError: 'field-error',
  alert: 'alert',
  submit: 'button',
};

export const Onboarding = () => (
  <CustomerOnboardingForm
    environment="sandbox"
    // YOUR backend route (the path is an example): mints a token for the sign-up session.
    // getTokenFromYourBackend is your own fetch helper, not part of the SDK.
    getHeaders={async () => ({
      Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/onboarding/token')}`,
    })}
    // YOUR code: receives { customerId, phoneNumber }. Save both on your backend, then verify
    // that phone.
    onSuccess={startPhoneVerification}
    onError={(error) => reportOnboardingFailure(error.kind)}
    fieldProps={FIELD_PROPS}
    classNames={CLASS_NAMES}
    submitProps={{ children: 'Create my account' }}
  />
);
```

```css
.form {
  display: grid;
  gap: 14px;
}
.field {
  display: grid;
  gap: 6px;
}
.field-label {
  font-size: 13px;
  font-weight: 600;
  color: #475569;
}
.input {
  width: 100%;
  height: 44px;
  box-sizing: border-box;
  padding: 0 12px;
  border: 1px solid #e6edf7;
  border-radius: 8px;
  background: #fff;
  font: inherit;
  color: #0b1220;
}
.input:focus,
.input:focus-within,
.input.vgs-collect-container__focused {
  outline: 0;
  border-color: #1f63f5;
  box-shadow: 0 0 0 3px #eff5ff;
}
.input[aria-invalid='true'] {
  border-color: #5826c3;
}
/* The SSN container is an .input; the secure iframe fills it. */
.input iframe {
  display: block;
  width: 100%;
  height: 100%;
  border: 0;
}
.field-error {
  font-size: 12.5px;
  color: #5826c3;
}
.alert {
  padding: 12px 14px;
  border: 1px solid #e6edf7;
  border-left: 3px solid #5826c3;
  border-radius: 8px;
  background: #fff;
  font-size: 14px;
  color: #475569;
}
.button {
  justify-self: start;
  padding: 10px 18px;
  border: 0;
  border-radius: 999px;
  background: #5826c3;
  color: #fff;
  font: inherit;
  font-weight: 600;
  cursor: pointer;
}
.button:disabled {
  opacity: 0.5;
  cursor: default;
}
```

<a id="css-layout"></a>

## CSS layout

Every row carries `data-field` with the field key, so a grid or flexbox rule arranges the drop-in form without touching the code. This one puts the name, city, state and ZIP rows side by side and hides the two optional fields.

```tsx
<CustomerOnboardingForm
  environment="sandbox"
  getHeaders={getHeaders}
  onSuccess={onSuccess}
  fieldProps={FIELD_PROPS}
  classNames={CLASS_NAMES}
  className="grid-form"
  hiddenFields={['middleName', 'addressLine2']}
  submitProps={{ children: 'Create my account' }}
/>
```

```css
/* Two columns; some rows span both. Rows carry data-field="<key>". */
.grid-form {
  display: grid;
  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
  gap: 14px 16px;
}
.grid-form [data-field='email'],
.grid-form [data-field='addressLine1'],
.grid-form [data-field='ssn'],
.grid-form .alert,
.grid-form .button {
  grid-column: 1 / -1;
}
```

<a id="custom-layout"></a>

## Custom layout

When the structure itself changes, the render prop hands you the pre-wired rows, the failure alert and the submit button, and you place them among your own headings and content. The SDK keeps the form element, the labels, the inline errors and the submit handling.

```tsx
<CustomerOnboardingForm
  environment="sandbox"
  getHeaders={getHeaders}
  onSuccess={onSuccess}
  fieldProps={FIELD_PROPS}
  classNames={CLASS_NAMES}
  submitProps={{ children: 'Create my account' }}
>
  {({ fields, alert, submitButton }) => (
    <>
      <h3>About you</h3>
      <div className="columns-2">
        {fields.firstName}
        {fields.lastName}
      </div>
      {fields.email}
      {fields.dateOfBirth}
      <h3>Home address</h3>
      {fields.addressLine1}
      <div className="columns-3">
        {fields.city}
        {fields.state}
        {fields.postalCode}
      </div>
      <h3>Verification</h3>
      {fields.phoneNumber}
      {fields.ssn}
      <p className="note">Your SSN goes straight to the secure vault; this page never sees it.</p>
      {alert}
      {submitButton}
    </>
  )}
</CustomerOnboardingForm>
```

```css
.columns-2 {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
  gap: 14px 16px;
}
.columns-3 {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 14px 16px;
}
.form h3 {
  margin: 8px 0 0;
  font-size: 15px;
  font-weight: 600;
  color: #0b1220;
}
.note {
  margin: 0;
  font-size: 13px;
  color: #64748b;
}
```

<a id="headless-rows"></a>

## Headless with the SDK rows

Drop the form element and keep the labelled rows. `OnboardingFormField` renders one row, label, field and linked error, anywhere inside `CoinmeOnboardingProvider`; the submit button is yours, driven by `useCustomerOnboarding`.

```tsx
import {
  CoinmeOnboardingError,
  CoinmeOnboardingProvider,
  OnboardingFormField,
  useCustomerOnboarding,
} from '@coinme-security/onboarding-sdk-react';

const SubmitButton = () => {
  const { isValid, submit, status } = useCustomerOnboarding({
    getHeaders,
    onSuccess,
  });
  return (
    <button
      className="button"
      disabled={!isValid || status === 'submitting' || status === 'success'}
      onClick={() =>
        submit().catch((failure: unknown) => {
          // A failed submit is a CoinmeOnboardingError; rethrow anything your onSuccess threw.
          if (!(failure instanceof CoinmeOnboardingError)) throw failure;
        })
      }
    >
      {status === 'submitting' ? 'Submitting…' : 'Create my account'}
    </button>
  );
};

export const Onboarding = () => (
  <CoinmeOnboardingProvider environment="sandbox">
    <fieldset>
      <legend>About you</legend>
      <div className="columns-2">
        <OnboardingFormField field="firstName" fieldProps={FIELD_PROPS.firstName} classNames={CLASS_NAMES} />
        <OnboardingFormField field="lastName" fieldProps={FIELD_PROPS.lastName} classNames={CLASS_NAMES} />
      </div>
      <OnboardingFormField field="email" fieldProps={FIELD_PROPS.email} classNames={CLASS_NAMES} />
      <OnboardingFormField field="dateOfBirth" fieldProps={FIELD_PROPS.dateOfBirth} classNames={CLASS_NAMES} />
    </fieldset>
    <fieldset>
      <legend>Address and verification</legend>
      <OnboardingFormField field="addressLine1" fieldProps={FIELD_PROPS.addressLine1} classNames={CLASS_NAMES} />
      <div className="columns-3">
        <OnboardingFormField field="city" fieldProps={FIELD_PROPS.city} classNames={CLASS_NAMES} />
        <OnboardingFormField field="state" fieldProps={FIELD_PROPS.state} classNames={CLASS_NAMES} />
        <OnboardingFormField field="postalCode" fieldProps={FIELD_PROPS.postalCode} classNames={CLASS_NAMES} />
      </div>
      <OnboardingFormField field="phoneNumber" fieldProps={FIELD_PROPS.phoneNumber} classNames={CLASS_NAMES} />
      <OnboardingFormField field="ssn" fieldProps={FIELD_PROPS.ssn} classNames={CLASS_NAMES} />
    </fieldset>
    <SubmitButton />
  </CoinmeOnboardingProvider>
);
```

```css
fieldset {
  display: grid;
  gap: 14px;
  margin: 0 0 18px;
  padding: 0;
  border: 0;
}
legend {
  margin-bottom: 8px;
  padding: 0;
  font-size: 15px;
  font-weight: 600;
  color: #0b1220;
}
```

<a id="headless"></a>

## Headless with bare fields

The whole UI is yours. The field components bind `name`, `value` and `onChange` and nothing else; labels, error display and the submit button come from your code through the hook. The secure SSN field still comes from the vault.

```tsx
import {
  AddressLine1Field,
  CityField,
  CoinmeOnboardingError,
  CoinmeOnboardingProvider,
  CoinmeSsnField,
  DateOfBirthField,
  DEFAULT_VALIDATION_MESSAGES,
  EmailField,
  FirstNameField,
  LastNameField,
  PhoneField,
  PostalCodeField,
  StateField,
  useCustomerOnboarding,
  type OnboardingFieldPath,
} from '@coinme-security/onboarding-sdk-react';

const FieldError = ({ path }: { path: OnboardingFieldPath }) => {
  const { fieldErrors, touched } = useCustomerOnboarding();
  const code = touched[path] ? fieldErrors[path] : undefined;
  return code ? <span className="field-error">{DEFAULT_VALIDATION_MESSAGES[code]}</span> : null;
};

const SubmitButton = () => {
  const { isValid, submit, status, error } = useCustomerOnboarding({ getHeaders, onSuccess });
  return (
    <>
      <button
        className="button"
        disabled={!isValid || status === 'submitting' || status === 'success'}
        onClick={() =>
          submit().catch((failure: unknown) => {
            // Shown below from `error`; rethrow anything your onSuccess threw.
            if (!(failure instanceof CoinmeOnboardingError)) throw failure;
          })
        }
      >
        Continue
      </button>
      {error && (
        <p role="alert" className="alert">
          {error.retryable ? 'Please try again.' : "We couldn't onboard you."}
        </p>
      )}
    </>
  );
};

export const Onboarding = () => (
  <CoinmeOnboardingProvider environment="sandbox">
    <div className="form">
      <label className="field">
        <span className="field-label">Email</span>
        <EmailField className="input" placeholder="you@example.com" />
        <FieldError path="email" />
      </label>
      <label className="field">
        <span className="field-label">First name</span>
        <FirstNameField className="input" />
        <FieldError path="fullName.firstName" />
      </label>
      <label className="field">
        <span className="field-label">Last name</span>
        <LastNameField className="input" />
        <FieldError path="fullName.lastName" />
      </label>
      <label className="field">
        <span className="field-label">Street address</span>
        <AddressLine1Field className="input" />
        <FieldError path="address.line1" />
      </label>
      <label className="field">
        <span className="field-label">City</span>
        <CityField className="input" />
        <FieldError path="address.city" />
      </label>
      <label className="field">
        <span className="field-label">State</span>
        <StateField className="input" />
        <FieldError path="address.state" />
      </label>
      <label className="field">
        <span className="field-label">ZIP code</span>
        <PostalCodeField className="input" />
        <FieldError path="address.postalCode" />
      </label>
      <label className="field">
        <span className="field-label">Phone number</span>
        <PhoneField className="input" />
        <FieldError path="phoneNumber" />
      </label>
      <label className="field">
        <span className="field-label">Date of birth</span>
        <DateOfBirthField className="input" />
        <FieldError path="dateOfBirth" />
      </label>
      <div className="field">
        <span className="field-label">Social Security Number</span>
        <CoinmeSsnField
          placeholder="123-45-6789"
          ariaLabel="Social Security Number"
          containerProps={{ className: 'input' }}
          css={{ fontSize: '16px', fontFamily: 'Inter, sans-serif', color: '#0b1220' }}
        />
      </div>
      <SubmitButton />
    </div>
  </CoinmeOnboardingProvider>
);
```

<a id="styling"></a>

## Styling

There is no theme object and no bundled CSS, so a form takes on your site by CSS alone. The variants here are the same drop-in form with a different stylesheet behind the same class names; the secure SSN field follows through its `css` option and its container class.

```tsx
/* The same drop-in form; only the class names' CSS changes. */
<CustomerOnboardingForm
  environment="sandbox"
  getHeaders={getHeaders}
  onSuccess={onSuccess}
  fieldProps={FIELD_PROPS}
  classNames={CLASS_NAMES}
  submitProps={{ children: 'Create my account' }}
/>
```

### Default

```css
/* The shared rules as they are: 44px inputs, 8px radius, purple pill button. */
```

### Compact

```css
.form { gap: 8px; }
.field { gap: 4px; }
.field-label { font-size: 12px; text-transform: uppercase; letter-spacing: 0.04em; }
.input { height: 36px; border-radius: 6px; font-size: 14px; }
.button { padding: 8px 14px; font-size: 14px; }
```

### Dark

```css
.form { color: #ece6fb; }
.field-label { color: #d7cbf4; }
.input {
  background: #130e2a;
  border-color: #2a2254;
  color: #ece6fb;
}
.input:focus,
.input:focus-within,
.input.vgs-collect-container__focused {
  border-color: #7fa6ff;
  box-shadow: 0 0 0 3px #1b1440;
}
.field-error { color: #b79dff; }
.alert { background: #130e2a; border-color: #2a2254; color: #d7cbf4; }
.button { background: #b79dff; color: #0a0518; }
```

### Rounded

```css
.input { height: 48px; padding: 0 16px; border-radius: 999px; border-width: 2px; }
.field-label { padding-left: 16px; }
.button { padding: 12px 24px; }
```
