Newsletter Components

NewsletterForm

Email capture form with validation and double opt-in

SubscriberPreferences

Manage email preferences and unsubscribe

Quick Start

Newsletter components are available from the SDK. Wrap your app with SylphxProvider for automatic configuration.

Installation

import { NewsletterForm, SubscriberPreferences } from '@sylphx/sdk/react'

NewsletterForm

A complete email capture form with validation, loading states, and success/error handling. Supports double opt-in and preference selection.

SSR Compatible

Auto-validation

Basic Usage

import { NewsletterForm } from '@sylphx/sdk/react'

export function Footer() {
  return (
    <footer>
      <h3>Subscribe to our newsletter</h3>
      <NewsletterForm />
    </footer>
  )
}

Props

Property	Type	Description
`variant`	`"inline" \| "stacked"`= "inline"	Layout variant - inline has input and button on same line
`preferences`	`string[]`= ["all"]	Pre-selected preferences for the subscriber
`showPreferences`	`boolean`= false	Show preference checkboxes in the form
`availablePreferences`	`Preference[]`	Available preferences to show as checkboxes
`source`	`string`= "website"	Source identifier for tracking signups
`metadata`	`object`	Additional metadata to attach to subscriber
`placeholder`	`string`= "Enter your email"	Email input placeholder text
`buttonText`	`string`= "Subscribe"	Submit button text
`successMessage`	`string`= "Check your email to confirm!"	Message shown after successful subscription
`onSuccess`	`(email: string) => void`	Callback when subscription is successful
`onError`	`(error: Error) => void`	Callback when subscription fails
`className`	`string`	Additional CSS classes for the form container

Variants

// Input and button on same line - great for footers
<NewsletterForm variant="inline" />

// Renders:
// +--------------------------------------------------+
// | [Enter your email...           ] [Subscribe]     |
// +--------------------------------------------------+

With Preferences

Show preference selection

<NewsletterForm
  showPreferences={true}
  availablePreferences={[
    { id: 'product_updates', label: 'Product Updates', description: 'New features & releases' },
    { id: 'promotions', label: 'Promotions', description: 'Special offers & discounts' },
    { id: 'weekly_digest', label: 'Weekly Digest', description: 'Best content summary' },
  ]}
  preferences={['product_updates']} // Pre-selected
/>

// Renders:
// +------------------------------------------+
// | [Enter your email...           ]         |
// |                                          |
// | ☑ Product Updates                        |
// |   New features & releases                |
// | ☐ Promotions                             |
// |   Special offers & discounts             |
// | ☐ Weekly Digest                          |
// |   Best content summary                   |
// |                                          |
// | [          Subscribe          ]          |
// +------------------------------------------+

Custom Styling

Themed form

<NewsletterForm
  variant="stacked"
  className="bg-gradient-to-br from-primary/10 to-primary/5 p-8 rounded-2xl"
  placeholder="your@email.com"
  buttonText="Get Updates"
  successMessage="🎉 You're in! Check your inbox."
  onSuccess={(email) => {
    analytics.track('newsletter_subscribed', { email })
  }}
/>

States

The component handles all states automatically:

Idle

Ready for input

Submitting subscription

Success

Shows confirmation message

Error

Shows error with retry

SubscriberPreferences

Allows subscribers to manage their email preferences, update frequency, or unsubscribe. Perfect for preference centers and unsubscribe pages.

SSR Compatible

Auto-fetching

Basic Usage

import { SubscriberPreferences } from '@sylphx/sdk/react'

// In your preference center page
export function PreferencesPage({ subscriberToken }: { subscriberToken: string }) {
  return (
    <div className="max-w-md mx-auto">
      <h1>Email Preferences</h1>
      <SubscriberPreferences token={subscriberToken} />
    </div>
  )
}

Props

Property	Type	Description
`token`	`string`	Subscriber token from email link (required)
`email`	`string`	Subscriber email (alternative to token if authenticated)
`showUnsubscribe`	`boolean`= true	Show unsubscribe from all option
`showFeedback`	`boolean`= true	Show feedback field on unsubscribe
`onUpdate`	`(preferences: string[]) => void`	Callback when preferences are updated
`onUnsubscribe`	`(reason?: string) => void`	Callback when user unsubscribes
`className`	`string`	Additional CSS classes

Unsubscribe Page

app/unsubscribe/page.tsx

import { SubscriberPreferences } from '@sylphx/sdk/react'

export default function UnsubscribePage({
  searchParams,
}: {
  searchParams: { token: string }
}) {
  return (
    <div className="min-h-screen flex items-center justify-center p-4">
      <div className="max-w-md w-full">
        <h1 className="text-2xl font-bold mb-2">Email Preferences</h1>
        <p className="text-muted-foreground mb-6">
          Choose which emails you'd like to receive, or unsubscribe from all.
        </p>

        <SubscriberPreferences
          token={searchParams.token}
          showFeedback={true}
          onUnsubscribe={(reason) => {
            // Track unsubscribe reason
            analytics.track('newsletter_unsubscribed', { reason })
          }}
        />
      </div>
    </div>
  )
}

Secure Tokens

The token in unsubscribe links is a signed JWT that identifies the subscriber. It expires after 30 days for security.

useNewsletter Hook

For custom UI, use the useNewsletter hook to access newsletter functionality:

Custom Newsletter Form

import { useNewsletter } from '@sylphx/sdk/react'

function CustomNewsletterForm() {
  const {
    subscribe,
    loading,
    error,
    success,
  } = useNewsletter()

  const [email, setEmail] = useState('')

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    await subscribe({
      email,
      preferences: ['product_updates'],
      source: 'custom_form',
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter your email"
        disabled={loading}
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Subscribing...' : 'Subscribe'}
      </button>

      {success && <p className="text-success">Check your email!</p>}
      {error && <p className="text-destructive">{error.message}</p>}
    </form>
  )
}

Hook Return Value

Property	Type	Description
`subscribe`	`(options) => Promise<void>`	Subscribe an email to the newsletter
`updatePreferences`	`(email, prefs) => Promise<void>`	Update subscriber preferences
`unsubscribe`	`(email, reason?) => Promise<void>`	Unsubscribe from newsletter
`loading`	`boolean`	Loading state for async operations
`error`	`Error \| null`	Error from last operation
`success`	`boolean`	Success state for last operation
`reset`	`() => void`	Reset success/error state

Best Practices

Prominent Placement

Place NewsletterForm in high-visibility areas: footer, sidebar, after valuable content.

Value Proposition

Tell users what they'll get. "Get weekly tips" is better than just "Subscribe".

Easy Unsubscribe

Make it easy to unsubscribe. It builds trust and is legally required.

Confirmation Feedback

Always show clear feedback after subscription. Guide users to check their email.

Quick Start

NewsletterForm

Props

Variants

With Preferences

Custom Styling

States

SubscriberPreferences

Props

Unsubscribe Page

Secure Tokens

useNewsletter Hook

Hook Return Value

Best Practices

Prominent Placement

Value Proposition

Easy Unsubscribe

Confirmation Feedback

Ready to build your newsletter?

Newsletter Overview

Referrals