Component Reference

WildwoodComponents is a comprehensive component library that provides drop-in solutions for authentication, AI chat, secure messaging, payments, subscriptions, and notifications. Available for Blazor, Razor Pages, React, React Native, and Node.js.

Multi-Platform: Components share the same API endpoints, --ww-* CSS theming system, and feature set across all platforms. Install via NuGet (.NET) or npm (JavaScript). See Installation for platform-specific setup.

BaseWildwoodComponent Architecture

Every component in the library extends BaseWildwoodComponent, which provides:

Automatic error handling — Errors are caught, logged, and surfaced via the OnError callback and ErrorMessage property.
Loading state management — Built-in IsLoading property and ShowLoadingStates parameter for consistent loading indicators.
Theme management — CSS custom properties (--ww-*) with automatic theme class generation via GetRootCssClasses().
Safe JS interop — Wrapped JavaScript calls with error handling through InvokeJSAsync and InvokeJSVoidAsync.
Unique component IDs — Each instance gets a unique ComponentId for DOM element targeting.

Shared Parameters (from BaseWildwoodComponent)

Parameter	Type	Default	Description
`CssClass`	`string?`	`null`	Additional CSS class applied to the component root element.
`ShowLoadingStates`	`bool`	`true`	Whether to display loading spinners during async operations.
`EnableErrorHandling`	`bool`	`true`	Whether to enable automatic error display within the component.
`OnError`	`EventCallback<ComponentErrorEventArgs>`	—	Fires when the component encounters an error.
`OnLoadingStateChanged`	`EventCallback<bool>`	—	Fires when the loading state changes.

Available Components

Component	Purpose	Key Features
AuthenticationComponent	Complete authentication solution	Local login, OAuth providers, passkeys/WebAuthn, 2FA, password reset, captcha, registration
AIChatComponent	AI conversational interface	Session management, text-to-speech, speech-to-text, multiple AI configurations, voice selection
SecureMessagingComponent	Real-time secure messaging	Threads (direct, group, channel), reactions, file sharing, typing indicators, read receipts
PaymentComponent	Multi-provider payment processing	Stripe, PayPal, Apple Pay, Google Pay, 3D Secure, BNPL, app store payments
SubscriptionComponent	Subscription lifecycle management	Plan selection, billing intervals, trial periods, upgrade/downgrade, cancellation
NotificationToastComponent	Toast notification system	4 notification types, auto-dismiss, custom actions, programmatic API via INotificationService

Platform Support

WildwoodComponents targets multiple Blazor hosting models. All components are designed for cross-platform compatibility.

Component	Blazor Server	Blazor WASM	MAUI	React	React Native
AuthenticationComponent	Full support	Full support	Full support	Full support	Full support
AIChatComponent	Full support	Full support	Full support (STT/TTS may vary)	Full support	Full support
SecureMessagingComponent	Full support	Full support	Full support	Full support	Full support
PaymentComponent	Full support	Full support	Platform-specific (App Store/Google Play)	Full support	Platform-specific (App Store/Google Play)
SubscriptionComponent	Full support	Full support	Full support	Full support	Full support
NotificationToastComponent	Full support	Full support	Full support	Full support	Full support

iOS/MAUI Note WildwoodComponents avoids LINQ methods internally to prevent iOS AOT runtime failures. If you extend the components, follow the same pattern — use foreach loops instead of .FirstOrDefault(), .Where(), etc.

Service Registration

// Program.cs
builder.Services.AddWildwoodComponents(options =>
{
    options.BaseUrl = "https://your-api.wildwood.example.com";
    options.ApiKey = "your-api-key";
});

// App.tsx
import { WildwoodProvider } from '@wildwood/react';

function App() {
  return (
    <WildwoodProvider config={{
      baseUrl: 'https://your-api.wildwood.example.com',
      appId: 'your-app-id',
      enableAutoTokenRefresh: true,
    }}>
      {/* All WildwoodComponents available here */}
    </WildwoodProvider>
  );
}

// App.tsx
import { WildwoodProvider } from '@wildwood/react-native';

function App() {
  return (
    <WildwoodProvider config={{
      baseUrl: 'https://your-api.wildwood.example.com',
      appId: 'your-app-id',
      storage: 'asyncStorage',
    }}>
      <Navigation />
    </WildwoodProvider>
  );
}

// server.ts
import { createAuthMiddleware, createAdminClient } from '@wildwood/node';

const auth = createAuthMiddleware({
  baseUrl: 'https://your-api.wildwood.example.com',
  apiKey: process.env.WILDWOOD_API_KEY,
});

app.use('/api', auth);

This registers all required services including IAuthenticationService, IAIService, ISecureMessagingService, IPaymentProviderService, ISubscriptionService, INotificationService, and supporting services.

Interactive Demo

Below is a live Blazor component demonstrating how WildwoodComponents styling adapts to themes. Toggle the dark mode icon in the header to see the form react to theme changes.

Live Demo Interactive - try clicking the elements below

Sample Login Form

This form uses --ww-* CSS variables. Toggle the docs theme (moon icon above) to see it adapt.

Password

Theming

All components use CSS custom properties prefixed with --ww-. You can override these variables to match your application's design system. Three built-in themes are available: woodland-warm (default), cool-blue, and fall-colors.

/* Override WildwoodComponents theme variables */
:root {
    --ww-primary: #6366F1;
    --ww-primary-dark: #4F46E5;
    --ww-bg-secondary: #1E293B;
    --ww-text-primary: #F8FAFC;
}

// React Native uses StyleSheet, not CSS variables
import { useTheme } from '@wildwood/react-native';

function ThemedScreen() {
  const { setTheme } = useTheme();

  // Switch to a built-in theme
  setTheme('cool-blue');

  // Or provide custom colors
  setTheme({
    primary: '#6366F1',
    primaryDark: '#4F46E5',
    bgSecondary: '#1E293B',
    textPrimary: '#F8FAFC',
  });
}

Activate a built-in theme via the data-theme attribute on your HTML element:

<html data-theme="cool-blue">