Component Library

Comprehensive guide to SuperBox reusable React components

Overview

SuperBox’s component library is built with React 19, TypeScript, and Tailwind CSS, providing a consistent and accessible UI across the application.

Fully Typed

All components are TypeScript-first with full type safety

Accessible

WCAG 2.1 AA compliant with keyboard navigation

Animated

Smooth animations powered by Framer Motion

Responsive

Mobile-first design with all breakpoints covered

Core Components

Header Component

The main navigation header with authentication and user menu.

Usage

import Header from '@/components/header'

export default function Layout({ children }) {
  return (
    <>
      <Header />
      <main>{children}</main>
    </>
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | transparent | boolean | false | Transparent background on scroll | | hideAuth | boolean | false | Hide authentication buttons | | className | string | '' | Additional CSS classes |

Features

• Responsive navigation menu
• User authentication status
• Profile dropdown menu
• Mobile hamburger menu
• Sticky header on scroll
• Dark mode support

Server Card Component

Display MCP server information in a card layout.

Basic Usage
import ServerCard from '@/components/server-card'

<ServerCard
  server={{
    id: "123",
    name: "Weather MCP",
    description: "Real-time weather data provider",
    author: "Areeb Ahmed",
    downloads: 1234,
    rating: 4.5,
    tags: ["weather", "api", "data"],
  }}
/>

server · object · required

Server data object

Show Server Object Properties

id · string · required

Unique server identifier

name · string · required

Server display name

description · string · required

Brief server description

author · string

Server creator username

downloads · number

Total download count

rating · number

Average rating (0-5)

tags · string[]

Server category tags

Auth Modal Component

Modal dialog for user authentication with multiple providers.

1. Import Component

   import AuthModal from '@/components/auth-modal'
   
2. Add to Layout

   const [showAuthModal, setShowAuthModal] = useState(false)
   
   return (
     <>
       <button onClick={() => setShowAuthModal(true)}>
         Sign In
       </button>
   
       <AuthModal
         isOpen={showAuthModal}
         onClose={() => setShowAuthModal(false)}
         defaultView="login"
       />
     </>
   )
   
3. Handle Callbacks

   <AuthModal
     isOpen={showAuthModal}
     onClose={() => setShowAuthModal(false)}
     onSuccess={(user) => {
       console.log('Authenticated:', user)
       setShowAuthModal(false)
     }}
     onError={(error) => {
       console.error('Auth failed:', error)
     }}
   />
   

The Auth Modal supports email/password, Google OAuth, and GitHub OAuth authentication methods.

Server Detail Component

Comprehensive server information display with tabs and actions.

import ServerDetail from "@/components/server-detail";

<ServerDetail serverId="server-123" initialData={serverData} />;

Server Detail Features

• Overview Tab: Description, stats, and quick actions - Tools Tab: List of available MCP tools - Documentation Tab: Markdown-rendered documentation - Reviews Tab: User ratings and reviews - Install Button: One-click installation via CLI - Share Button: Social sharing options - Report Button: Security issue reporting

Tool Card Component

Display individual MCP tool information.

Tool Card
import ToolCard from '@/components/tool-card'

<ToolCard
  tool={{
    name: "get_weather",
    description: "Fetch current weather data",
    parameters: {
      city: { type: "string", required: true },
      units: { type: "string", enum: ["metric", "imperial"] },
    },
    returns: {
      type: "object",
      properties: {
        temperature: "number",
        conditions: "string",
      },
    },
  }}
/>

Custom Dropdown Component

Accessible dropdown menu with keyboard navigation.

import CustomDropdown from "@/components/custom-dropdown";

<CustomDropdown
  trigger={<button>Options</button>}
  items={[
    { label: "Edit", icon: "pencil", onClick: handleEdit },
    { label: "Delete", icon: "trash", onClick: handleDelete },
    { type: "separator" },
    { label: "Share", icon: "share", onClick: handleShare },
  ]}
/>;

Dropdown automatically closes on outside click and Escape key press for better UX.

Toast Provider Component

Global toast notification system.

Setup

app/layout.tsx
import ToastProvider from '@/components/toast-provider'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ToastProvider />
        {children}
      </body>
    </html>
  )
}

Usage

import { toast } from '@/components/toast-provider'

// Success toast
toast.success('Server installed successfully!')

// Error toast
toast.error('Failed to connect to server')

// Info toast
toast.info('New update available')

// Warning toast
toast.warning('API rate limit approaching')

// Custom toast
toast.custom('Custom message', {
  duration: 5000,
  position: 'top-center',
  icon: 'rocket'
})

Options

Option	Type	Default	Description
duration	number	3000	Toast duration in ms
position	string	'bottom-right'	Toast position
icon	string	Auto	Custom icon emoji
dismissible	boolean	true	Show close button

Paywall Modal Component

Premium features upgrade modal with Razorpay integration.

import PaywallModal from "@/components/paywall-modal";

<PaywallModal
  isOpen={showPaywall}
  onClose={() => setShowPaywall(false)}
  feature="Advanced Search"
  plan="pro"
/>;

Publish Modal Component

Multi-step wizard for publishing MCP servers.

1. Server Details

   Name, description, and category selection
2. Tool Configuration

   Define MCP tools and parameters
3. Security Scan

   Automated security checks (SonarQube, Bandit, GitGuardian)

4. Review & Publish

   Final review before publishing to marketplace

import PublishModal from "@/components/publish-modal";

<PublishModal
  isOpen={showPublish}
  onClose={() => setShowPublish(false)}
  onSuccess={(server) => {
    toast.success("Server published!");
    router.push(`/server/${server.id}`);
  }}
/>;

Reviews Section Component

Display and manage user reviews with ratings.

import ReviewsSection from "@/components/reviews-section";

<ReviewsSection
  serverId="server-123"
  averageRating={4.5}
  totalReviews={42}
  userReview={{
    rating: 5,
    comment: "Excellent MCP server!",
  }}
/>;

Security Report Component

Report security vulnerabilities in MCP servers.

import SecurityReport from "@/components/security-report";

<SecurityReport serverId="server-123" serverName="Weather MCP" />;

Page Transition Component

Smooth page transitions with Framer Motion.

app/layout.tsx
import PageTransition from "@/components/page-transition";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <PageTransition>{children}</PageTransition>
      </body>
    </html>
  );
}

Wave Background Component

Animated SVG wave background for hero sections.

import WaveBackground from "@/components/wave-background";

<section className="relative">
  <WaveBackground />
  <div className="relative z-10">
    <h1>Welcome to SuperBox</h1>
  </div>
</section>;

Component Patterns

Composition Pattern

Build complex UIs by composing simple components:

<ServerCard server={server}>
  <ServerCard.Header>
    <ServerCard.Title>{server.name}</ServerCard.Title>
    <ServerCard.Badge>{server.category}</ServerCard.Badge>
  </ServerCard.Header>

  <ServerCard.Body>
    <ServerCard.Description>{server.description}</ServerCard.Description>
    <ServerCard.Stats downloads={server.downloads} rating={server.rating} />
  </ServerCard.Body>

  <ServerCard.Footer>
    <ServerCard.InstallButton serverId={server.id} />
    <ServerCard.FavoriteButton serverId={server.id} />
  </ServerCard.Footer>
</ServerCard>

Render Props Pattern

Share logic between components:

<DataFetcher url="/api/servers">
  {({ data, loading, error }) => {
    if (loading) return <Skeleton />;
    if (error) return <ErrorMessage error={error} />;
    return <ServerList servers={data} />;
  }}
</DataFetcher>

Custom Hooks

Reusable logic extracted into hooks:

import { useAuth } from "@/lib/hooks/use-auth";
import { useServers } from "@/lib/hooks/use-servers";

function MyComponent() {
  const { user, isAuthenticated } = useAuth();
  const { servers, loading } = useServers({ userId: user?.id });

  // Component logic
}

Styling Guidelines

Use Tailwind CSS utility classes for styling. Avoid custom CSS unless absolutely necessary.

Common Patterns

// Card styling
className = "bg-white dark:bg-gray-800 rounded-lg shadow-md p-6";

// Button styling
className =
  "px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded-md transition-colors";

// Input styling
className =
  "w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500";

// Responsive layout
className = "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6";

Accessibility Features

All components follow WCAG 2.1 AA standards:

Keyboard Navigation - Full keyboard support with focus management

Screen Readers - Semantic HTML and ARIA attributes

Color Contrast - Minimum 4.5:1 contrast ratio

Focus Indicators - Visible focus states for all interactive elements

Next Steps

Setup Guide

Set up your development environment

Deployment

Deploy to Vercel

API Integration

Connect to backend APIs

Backend Overview

Learn about the backend