npm package: @fundably/connect
Description: Fundably Connect — embed the Fundably application form into any website
Author: Fundably
Latest version: 1.7.15

# @fundably/connect

Embed the Fundably business funding application form into any website with a single HTML tag. Works in React, Vue, Angular, Svelte, WordPress, Webflow — or plain HTML.

## Quick Start

### CDN (no build tools)

```html
<script src="https://unpkg.com/@fundably/connect/dist/index.iife.js"></script>

<fundably-connect referral-code="YOUR_REFERRAL_CODE"></fundably-connect>
```

### npm

```bash
npm install @fundably/connect
```

```js
import '@fundably/connect';
```

```html
<fundably-connect referral-code="YOUR_REFERRAL_CODE"></fundably-connect>
```

### React

```tsx
import '@fundably/connect';

function App() {
  return (
    <fundably-connect
      referral-code="YOUR_REFERRAL_CODE"
      auto-resize
    />
  );
}
```

> **React 18 and below:** Custom element events don't propagate through React's synthetic event system. Use a `ref` to listen for the `applicationsubmitted` event:
>
> ```tsx
> import { useRef, useEffect } from 'react';
> import '@fundably/connect';
>
> function App() {
>   const ref = useRef<HTMLElement>(null);
>
>   useEffect(() => {
>     const el = ref.current;
>     if (!el) return;
>     const handler = (e: Event) => {
>       const detail = (e as CustomEvent).detail;
>       console.log('Application submitted:', detail.applicationId);
>     };
>     el.addEventListener('applicationsubmitted', handler);
>     return () => el.removeEventListener('applicationsubmitted', handler);
>   }, []);
>
>   return <fundably-connect ref={ref} referral-code="YOUR_CODE" auto-resize />;
> }
> ```
>
> React 19+ supports custom element events natively.

## Attributes

| Attribute       | Type      | Default                      | Description                                                         |
| --------------- | --------- | ---------------------------- | ------------------------------------------------------------------- |
| `referral-code` | `string`  | —                            | **(Required)** Your partner referral code.                          |
| `env`           | `string`  | `"prod"`                     | Environment: `"prod"` or `"stage"`. Use `"stage"` for testing.        |
| `base-url`      | `string`  | `https://app.fundably.com`   | Override the application URL entirely (advanced).                   |
| `height`        | `string`  | `700px`                      | Initial iframe height. Ignored when `auto-resize` is set.           |
| `auto-resize`   | `boolean` | `false`                      | Automatically adjust height to match the embedded form's content.   |

## Events

| Event                  | `detail`                       | Description                                          |
| ---------------------- | ------------------------------ | ---------------------------------------------------- |
| `applicationsubmitted` | `{ applicationId: string }`    | Fired when the applicant successfully submits their application. |
| `applicationdeclined`  | `{ reason: string }`           | Fired when Fundably declines the application (e.g. sole traders are not eligible). |

```js
const el = document.querySelector('fundably-connect');

el.addEventListener('applicationsubmitted', (e) => {
  console.log('Application submitted:', e.detail.applicationId);
});

el.addEventListener('applicationdeclined', (e) => {
  console.log('Application declined by Fundably:', e.detail.reason);
  // Show a fallback message or redirect the user
});
```

## Versioning

The package version mirrors the Fundably form schema version. When the form is updated (e.g. new fields, changed steps), a new SDK version is published with the matching version number. The component itself is a thin wrapper — updates to the form are delivered through the embedded application, not the SDK.

## Testing before going live

Set `env="stage"` to point at the Fundably staging environment. Remove it (or set to `"prod"`) when you're ready to go live:

```html
<fundably-connect
  referral-code="YOUR_REFERRAL_CODE"
  env="stage"
  auto-resize
></fundably-connect>
```

## Browser Support

Works in all browsers that support [Custom Elements v1](https://caniuse.com/custom-elementsv1) — Chrome, Firefox, Safari, Edge (all modern versions).

## License

MIT