Theming, Whitelabeling & Custom Domains
Relevant source files
The following files were used as context for generating this wiki page:
KudosWall provides a robust system for customizing the visual identity of testimonial collection campaigns and display widgets. This system allows users to align the platform's appearance with their own brand through advanced theming options, whitelabeling capabilities, and the use of custom domains for public-facing pages.
The high-level architecture leverages a decoupled design where the collection page and the display widget are treated as distinct design surfaces, allowing for separate branding strategies for the submission flow and the final social proof display.
Sources: README.md:46-48, apps/web/src/lib/comparisons.tsx:112-117
Theming Architecture
Theming is implemented through a combination of JSON-based configuration objects and dynamic CSS injection. Users can configure accent colors, background styles, and typography across 35+ Google Fonts.
Collection Page Configuration
Collection pages use a deep-merged settings object to define the UI. This includes specific configurations for the form fields, page content (headlines/subheadings), and compliance elements like cookie banners.
The diagram shows how settings are retrieved from the database and merged with defaults before being rendered.
Sources: apps/web/src/app/collect/[slug]/page.tsx:82-160, README.md:46-48
Key Theming Parameters
The system supports several visual override categories:
| Parameter | Type | Description |
|---|---|---|
accentColor | Hex String | Primary brand color used for buttons, icons, and focus states. |
backgroundColor | Hex String | Background color for the collection page or widget container. |
fontFamily | String | Selection from 35+ Google Fonts or a custom font URL. |
background.type | Enum | Supports color, gradient, or image. |
customCss | String | Raw CSS overrides for deep UI modifications (Pro only). |
Sources: apps/web/src/app/collect/[slug]/page.tsx:83-140, README.md:46-48
Whitelabeling System
Whitelabeling in KudosWall is a plan-gated feature that allows the removal of "Powered by KudosWall" branding and the total customization of the UI to appear as a native part of the user's site.
Branding Logic
The application checks the workspace's plan status to determine if branding should be displayed. Plans such as Pro, Agency, and Lifetime allow for the removal of the KudosWall badge.
This sequence illustrates the plan-based conditional rendering of the platform badge.
Sources: apps/web/src/app/wall/[slug]/page.tsx:69-75, apps/web/src/app/(marketing)/free/page.tsx:115-125
Implementation Details
- Badge Removal: Managed via the
isBadgeRemovedflag andhideBadgesetting. On public walls, this is influenced by thebadgeRemovedUntiltimestamp in the database. - Custom CSS: Users on higher-tier plans can inject raw CSS into their collection pages using the
customCssfield, which is rendered directly in a<style>tag. - Logo Customization: Workspaces can upload a
logoUrlwhich replaces default branding in headers and favicon slots.
Sources: apps/web/src/app/wall/[slug]/page.tsx:73-75, apps/web/src/app/collect/[slug]/page.tsx:215-217, README.md:46-48
Custom Domains & Edge Proxy
For a seamless whitelabeled experience, KudosWall supports custom domains (e.g., reviews.yourbrand.com). This is facilitated by an edge-compatible proxy handler rather than standard Next.js middleware to ensure stability on Cloudflare.
Proxy Logic
The system uses src/proxy.ts to route requests from custom domains to the correct internal workspace and project paths.
The edge proxy handles domain resolution to provide zero-latency routing for whitelabeled domains.
Sources: README.md:52-54, AGENTS.md:52-54
SEO and Metadata Customization
Public walls and collection pages dynamically generate metadata based on the project's branding settings. This includes:
- Favicons: Loaded from
projectData.settings.faviconUrl. - OpenGraph Images: Generated via a dedicated OG API using the project's specific branding and slug.
- JSON-LD: Injection of structured data (Product, Review, AggregateRating) for SEO visibility.
Sources: apps/web/src/app/wall/[slug]/page.tsx:23-53, apps/web/src/app/collect/[slug]/page.tsx:23-53
Plan-Gated Feature Matrix
| Feature | Free Tier | Pro / Agency Tier |
|---|---|---|
| Branding Badge | Mandatory "Powered by" | Removable |
| Custom Domains | Not Available | Supported |
| Layout Options | Grid only | Carousel, Marquee, List, Grid |
| Custom CSS | Not Available | Supported |
| Advanced Filtering | Not Available | Tag & Rating Filtering |
Sources: apps/web/src/app/(marketing)/free/page.tsx:115-135, apps/web/src/lib/comparisons.tsx:442-455
Conclusion
Theming and whitelabeling are core components of the KudosWall SaaS architecture, designed to provide users with a "native" feel for their social proof assets. By utilizing edge-based proxying for custom domains and a flexible JSON-based settings engine, the platform ensures that branding is consistent across all visitor touchpoints while maintaining high performance and SEO integrity.