React Tally Wrapper

A lightweight React wrapper for embedding Tally.so forms with ease.\ Supports all Tally embed features, event listeners, and customization options via props.

Features

• ✅ Easy integration of Tally forms in React, Astro and Next.js apps
• 🎯 Event handlers for form load, page view, and submission
• 🪄 Utility methods and hooks to work with the Tally widget and session
• 💥 TypeScript ready

Installation

npm install react-tally
# or
bun add react-tally

Usage

As an embed

import { TallyForm } from 'react-tally';

function MyPage() {
    return (
        <TallyForm
            formId="YOUR_FORM_ID"
            onFormLoad={(event) => console.log('Form loaded', event)}
            onPageView={(event) => console.log('Page viewed', event)}
            onSubmission={(event) => console.log('Form submitted', event)}
            style={{ width: '100%', height: '500px' }}
        />
    );
}

Props

All standard <iframe /> props are supported.\ In addition, the following are available:

As a popup

import { useTallyPopup } from 'react-tally';

function MyPage() {
    const { open, close } = useTallyPopup('YOUR_FORM_ID');

    return (
        <div>
            <button onClick={() => open()}>Open</button>
            <button onClick={() => close()}>Close</button>
        </div>
    );
}

The open() function may take additional configuration options:

type TallyPopupOptions = {
    key?: string; // This is used as a unique identifier used for the "Show only once" and "Don't show after submit" functionality
    layout?: 'default' | 'modal';
    width?: number;
    alignLeft?: boolean;
    hideTitle?: boolean;
    overlay?: boolean;
    emoji?: {
        text: string;
        animation:
            | 'none'
            | 'wave'
            | 'tada'
            | 'heart-beat'
            | 'spin'
            | 'flash'
            | 'bounce'
            | 'rubber-band'
            | 'head-shake';
    };
    autoClose?: number; // in milliseconds
    showOnce?: boolean;
    doNotShowAfterSubmit?: boolean;
    customFormUrl?: string; // when you want to load the form via it's custom domain URL
    hiddenFields?: {
        [key: string]: any;
    };
    onOpen?: () => void;
    onClose?: () => void;
    onPageView?: (page: number) => void;
    onSubmit?: (payload: TallySubmissionPayload) => void;
};

Utility Hooks and Functions

You can also use these utilities:

import {
    // Hooks
    useTally,
    useTallyEvents,

    // Functions
    getFormData,
    getFormSession,
} from 'react-tally';

• getFormData(formId: string): TallyFormData | undefined\ Fetch metadata about a given form.

• getFormSession(formId: string): string | undefined\ Access current session ID for a specific form.

• useTally(): void\ Injects the Tally popup widget script.

• useTallyEvents(formId:string, { onFormLoad, onPageView, onSubmission }: TallyEventHandlers): void\ Tally form event listeners for a specified form.

• useTallyEvents({ onFormLoad, onPageView, onSubmission }: TallyEventHandlers): void\ Tally form event listeners for all Tally events.

License

MIT

Credits

Based on the Tally.so Developer Resources.