Site Banner System

TinyKit Pro includes a comprehensive site banner system for displaying promotional announcements, maintenance notices, and important updates across the platf...

TinyKit Pro includes a comprehensive site banner system for displaying promotional announcements, maintenance notices, and important updates across the platform.

🎯 Smart Targeting: Display banners on specific pages (root, home, teams)
🎨 Theme Integration: Theme Match preset automatically adapts to site branding
⏰ Scheduling: Schedule banners to activate/deactivate at specific times
💳 Stripe Integration: Connect banners to promotion codes for automated discounts
📱 Responsive Design: Banners adapt beautifully to all screen sizes
⚡ Real-time Preview: Live preview while configuring banner settings
🔄 Display Order: Drag-and-drop ordering for multiple active banners

General Presets

Theme Match

Dynamic Colors: Automatically matches your site's selected theme colors
CSS Variables: Uses semantic color tokens for dynamic adaptation
Brand Integration: Perfect for announcements that match your brand
Smart Selection: Choose from Primary, Secondary, Accent, Muted, Destructive, Card colors

Promotional Presets

Black Friday

Colors: Traditional black background with red accents
Use Case: Black Friday promotions and sales events
Urgency: High-contrast design for maximum impact

Product Hunt

Colors: Orange gradient theme with vibrant accents
Use Case: Product Hunt launches and startup announcements
Energy: Energetic gradient for excitement generation

Holiday Sale

Colors: Festive red and green theme
Use Case: Holiday promotions and seasonal sales
Festive: Holiday-themed color scheme

Cyber Monday

Colors: Blue/tech theme with modern gradients
Use Case: Cyber Monday deals and tech promotions
Professional: Tech-focused color palette

Informational Presets

System Maintenance

Colors: Yellow warning theme with clear contrast
Use Case: Maintenance notifications and system downtime
Visibility: High-visibility warning colors

Feature Launch

Colors: Purple gradient for new feature announcements
Use Case: Product updates and feature releases
Innovation: Modern gradient for forward-thinking messaging

Dynamic Color Selection

The Theme Match preset provides intelligent integration with site branding:

// Available background colors
- Primary: Main brand color with optimal contrast
- Secondary: Secondary theme color
- Accent: Accent color for highlights
- Muted: Subdued backgrounds for less important content
- Destructive: Error states and warnings
- Card: Card and container backgrounds

Smart Interface Adaptation

Theme Detection: Automatically detects when CSS variables are active
Selective UI: Hides color presets for theme banners to avoid confusion
Visual Indicators: Clear labels show when theme colors are active
Live Preview: See color changes instantly in banner preview

Navigate to /admin/site-banners for comprehensive banner management.

Content Settings

Message Text: Banner content with rich text support
Call-to-Action: Optional link with custom button text
Page Targeting: Select pages where banner should appear (root, home, teams)
Activity Control: Enable/disable banners instantly

Appearance Settings

Preset Selection: Choose from pre-built color schemes or Theme Match
Custom Colors: Fine-tune colors with color picker
Preview System: Real-time banner preview during configuration

Advanced Features

Stripe Integration: Connect to promotion codes for automatic discounts
Scheduling System: Set start/end dates with precise timing
Auto-Apply Coupons: Automatically apply discounts during checkout
Subscriber Filtering: Show/hide banners for existing subscribers

Live Status: Visual indicators for active/inactive banners
Display Order: Drag handles for manual ordering when multiple banners active
Quick Actions: Toggle activation, edit settings, or delete banners
Preview Cards: Thumbnail previews of banner appearance

Bulk Operations

Multi-Select: Select multiple banners for bulk operations
Batch Toggle: Enable/disable multiple banners at once
Order Management: Reorder multiple banners efficiently

Technical Implementation

Database Schema

interface SiteBanner {
  _id: Id<"siteBanners">;
  text: string; // Banner message
  backgroundColor: string; // Hex color or CSS variable
  textColor: string; // Hex color or CSS variable
  linkUrl?: string; // Optional CTA link
  linkText?: string; // CTA button text
  showOnPages: ("root" | "home" | "teams")[];
  isActive: boolean; // Display status
  displayOrder: number; // Sort order for multiple banners

  // Preset Information
  presetType?: string; // Which preset was used

  // Stripe Integration
  stripePromotionCodeId?: string; // Stripe promotion code
  triggerParam?: string; // URL parameter trigger
  autoApplyAtCheckout?: boolean; // Auto-apply discount
  showToSubscribers?: boolean; // Show to existing subscribers

  // Scheduling
  scheduleStartDate?: number; // Auto-activation timestamp
  scheduleEndDate?: number; // Auto-deactivation timestamp

  createdAt: number;
  updatedAt: number;
}

Frontend Components

StickyBanner Component

Responsive Design: Adapts to different screen sizes
Dismiss Functionality: Users can dismiss banners
Smart Positioning: Appears above all content with proper z-index
Animation Support: Smooth show/hide transitions

BannerFormPage: Comprehensive banner creation/editing interface
ThemeColorSelect: Theme-aware color selection dropdown
PresetCard: Visual preset selection with live preview
BannerPreview: Real-time banner preview component

Smart Positioning System

Layout Integration

/* Dynamic height calculation for layout adjustment */
:root {
  --banner-height: 0px; /* Default when no banners */
}

.banner-active {
  --banner-height: 48px; /* Adjust based on banner height */
}

/* Page layouts automatically adjust */
.main-content {
  padding-top: calc(3.5rem + var(--banner-height, 0px));
}

Responsive Behavior

Mobile Optimization: Banner height adjusts for mobile screens
Content Preservation: Main content never overlaps with banners
Smooth Transitions: CSS transitions for banner show/hide
Z-Index Management: Proper layering with other fixed elements

Creating Banners Programmatically

import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";

const createBanner = useMutation(api.siteBanners.public.mutations.createBanner);

// Create a theme-aware banner
await createBanner({
  text: "🎉 New Feature Launch - Check it out!",
  backgroundColor: "var(--primary)",
  textColor: "var(--primary-foreground)",
  showOnPages: ["root", "home"],
  isActive: true,
  presetType: "themeMatch",
});

// Create a promotional banner with Stripe integration
await createBanner({
  text: "🔥 Black Friday Sale - 50% Off!",
  backgroundColor: "#000000",
  textColor: "#ffffff",
  linkUrl: "/pricing",
  linkText: "Claim Offer",
  showOnPages: ["root"],
  isActive: true,
  presetType: "blackFriday",
  stripePromotionCodeId: "promo_blackfriday50",
  autoApplyAtCheckout: true,
  scheduleStartDate: Date.now(),
  scheduleEndDate: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
});

// Get all banners for admin management
const allBanners = useQuery(api.siteBanners.public.queries.getAllBanners);

// Get active banners for display on specific page
const activeBanners = useQuery(
  api.siteBanners.public.queries.getActiveBanners,
  { page: "home" },
);

// Get banners with scheduling information
const scheduledBanners = useQuery(
  api.siteBanners.public.queries.getScheduledBanners,
);

// Update banner settings
const updateBanner = useMutation(api.siteBanners.public.mutations.updateBanner);

await updateBanner({
  bannerId: banner._id,
  updates: {
    text: "Updated banner message",
    isActive: true,
  },
});

// Toggle banner activation
const toggleBanner = useMutation(api.siteBanners.public.mutations.toggleBanner);

await toggleBanner({ bannerId: banner._id });

// Delete banner
const deleteBanner = useMutation(api.siteBanners.public.mutations.deleteBanner);

await deleteBanner({ bannerId: banner._id });

Integration with Site Branding

Automatic Theme Integration

Banners integrate seamlessly with the site branding system:

Theme Colors: Automatically pull from site settings color palette
Brand Consistency: Theme Match preset ensures brand alignment
Dynamic Updates: Color changes in admin settings immediately affect theme banners
Fallback Values: Graceful degradation if branding data unavailable

CSS Variable Usage

// Theme-aware banner styling
const bannerStyles = {
  backgroundColor:
    banner.presetType === "themeMatch"
      ? `var(--${banner.backgroundColor})`
      : banner.backgroundColor,
  color:
    banner.presetType === "themeMatch"
      ? `var(--${banner.textColor})`
      : banner.textColor,
};

Best Practices

Content Guidelines

Concise Messaging: Keep banner text under 200 characters
Clear CTAs: Use action-oriented language for links
Urgency Balance: Create urgency without being overwhelming
Brand Voice: Maintain consistent brand voice across all banners

Technical Best Practices

Performance: Banners load asynchronously to avoid blocking page render
Accessibility: Proper color contrast and keyboard navigation support
SEO Impact: Banners don't negatively affect search engine optimization
Mobile Experience: Banners optimized for mobile interaction patterns

Scheduling Strategy

Lead Time: Schedule banners with adequate planning time
Overlap Management: Avoid conflicting messages from multiple active banners
Timezone Awareness: Consider user timezone distribution for scheduling
Event Coordination: Coordinate banner schedules with marketing campaigns

Stripe Integration Best Practices

Promotion Codes: Create specific promotion codes for banner campaigns
Auto-Apply: Use auto-apply for better user experience
Tracking: Monitor promotion code usage and effectiveness
Subscriber Filtering: Consider whether existing subscribers should see promotional banners

Troubleshooting

Common Issues

Banner not appearing on expected pages

Verify showOnPages array includes the correct page identifiers
Check that banner is active (isActive: true)
Ensure banner hasn't expired if scheduling is enabled

Theme colors not displaying correctly

Verify site branding is configured in admin settings
Check that CSS variables are properly loaded
Ensure fallback colors are defined

Banner overlapping with content

Check CSS variable --banner-height is being set correctly
Verify layout components account for banner height
Ensure z-index values are properly configured

Stripe promotion not applying

Verify promotion code exists in Stripe dashboard
Check that stripePromotionCodeId matches Stripe promotion code ID
Ensure promotion code is active and not expired

Debug Commands

# Monitor banner-related logs
npx convex logs --tail | grep "banner\|siteBanner"

# Check banner database records
npx convex dashboard
# Navigate to siteBanners table

# Test banner display logic
# Use browser developer tools to verify CSS variables

← Previous: Notifications | Next: Email Templates →

On this page