fansunited-sports-ui

A comprehensive React component library for building sports websites and applications. Built with Tailwind CSS v4 for seamless theming integration.

Features

• 🏟️ Sports-focused — Purpose-built for media sites, football clubs, federations, and betting affiliates
• 🎨 Tailwind CSS v4 — Uses native Tailwind classes to automatically match your design system
• 📦 Three-layer architecture — Primitives, Components, and Blocks for flexible composition
• 🎯 Type-Safe — Full TypeScript support with comprehensive type definitions
• 🔧 Highly Customizable — Flexible styling system with standardized customization options
• 📱 Responsive — Mobile-first design that works on all screen sizes
• 🎭 Theme Support — Works with Tailwind's theme system and custom color palettes

Installation

Install the package via npm:

npm install fansunited-sports-ui

Peer Dependencies

This library requires the following peer dependencies:

{
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0",
    "tailwindcss": "^4.0.0",
    "@tailwindcss/postcss": "^4.0.0"
}

Install them if you haven't already:

npm install react react-dom tailwindcss @tailwindcss/postcss

Setup

1. Configure Tailwind CSS

Update your Tailwind CSS configuration to scan the component library files. This ensures that all Tailwind classes used by the components are included in your build.

For Tailwind CSS v4 with @import in CSS:

In your main CSS file (e.g., src/index.css or app/globals.css):

@import "tailwindcss";

/* Your custom theme and styles */

Configure content paths in tailwind.config.js (or tailwind.config.ts):

/** @type {import('tailwindcss').Config} */
export default {
    content: [
        "./index.html",
        "./src/**/*.{js,ts,jsx,tsx}",
        // Add this line to scan the component library
        "./node_modules/fansunited-sports-ui/dist/**/*.{js,mjs,cjs}",
    ],
    theme: {
        extend: {},
    },
    plugins: [],
};

Important: The component library uses Tailwind's native color classes (e.g., bg-primary-600, from-primary-600) instead of hardcoded colors. This means the components will automatically match your application's design system and theme.

2. Configure PostCSS

Ensure your postcss.config.js includes the Tailwind CSS PostCSS plugin:

export default {
    plugins: {
        "@tailwindcss/postcss": {},
        autoprefixer: {},
    },
};

3. Define Your Theme (Optional)

The components use Tailwind's color system. You can customize the primary and secondary colors in your CSS using the @theme directive:

@import "tailwindcss";

@theme {
    /* Primary color palette */
    --color-primary-50: oklch(0.97 0.01 250);
    --color-primary-100: oklch(0.93 0.03 250);
    --color-primary-200: oklch(0.85 0.06 250);
    --color-primary-300: oklch(0.75 0.1 250);
    --color-primary-400: oklch(0.65 0.14 250);
    --color-primary-500: oklch(0.57 0.17 250);
    --color-primary-600: oklch(0.5 0.17 250);
    --color-primary-700: oklch(0.43 0.15 250);
    --color-primary-800: oklch(0.35 0.12 250);
    --color-primary-900: oklch(0.27 0.09 250);
    --color-primary-950: oklch(0.18 0.06 250);

    /* Secondary color palette */
    --color-secondary-50: oklch(0.97 0.02 50);
    --color-secondary-100: oklch(0.94 0.04 50);
    --color-secondary-200: oklch(0.88 0.08 50);
    --color-secondary-300: oklch(0.8 0.12 50);
    --color-secondary-400: oklch(0.72 0.15 50);
    --color-secondary-500: oklch(0.68 0.18 50);
    --color-secondary-600: oklch(0.62 0.18 50);
    --color-secondary-700: oklch(0.54 0.16 50);
    --color-secondary-800: oklch(0.45 0.13 50);
    --color-secondary-900: oklch(0.36 0.1 50);
    --color-secondary-950: oklch(0.25 0.07 50);
}

Quick Start

Basic Usage

Import and use the components in your React application:

import { MatchScore, ContentCard } from "fansunited-sports-ui";

function App() {
    return (
        <MatchScore
            match={{
                id: "1",
                competitorOne: { id: "1", name: "Arsenal", score: { main: 2 } },
                competitorTwo: { id: "2", name: "Chelsea", score: { main: 1 } },
                status: "final",
            }}
            variant="scoreCard"
        />
    );
}

Architecture

The library is organized into three layers:

Layer 1: Primitives

Pure UI building blocks with no domain knowledge:

| Component | Description | | ------------------------ | ---------------------------------- | | Badge / BadgeGroup | Status labels and tags | | CtaButton / CtaGroup | Call-to-action buttons | | EntityDisplay | Generic entity with image and name | | Countdown | Timer display | | Pagination | Page navigation | | Tooltip | Hover information |

Layer 2: Components

Domain-aware components with single responsibility:

| Component | Description | | ----------------- | ------------------------------------------------------------------------------------------ | | MatchScore | Match display with variants: inline, scoreCard, scoreLine, embedded | | ContentCard | Flexible cards with variants: hero, standard, standardHorizontal, promo, minimal | | BettingOdds | Odds display with operator branding | | StatsTable | Tabular statistics (standings, leaderboards) | | StatsGrid | Grid of stat items | | StatsHeadToHead | Comparison bars | | FormIndicator | Win/draw/loss form display | | ProfileHeader | Entity profile headers | | MatchupHeader | Two-entity matchup display | | SectionHeader | Section titles with optional actions |

Layer 3: Blocks

Pre-assembled composites ready for use:

| Block | Description | | ------------------------ | --------------------------------- | | MatchListBlock | List of matches with grouping | | ContentListBlock | Grid/list of content cards | | FeaturedContentBlock | Hero + supporting content layouts | | HeadToHeadBlock | Complete H2H comparison | | CompetitorProfileBlock | Full competitor profile | | SquadBlock | Team squad display |

Styling

Every component accepts a styles prop for customization:

<MatchScore
    match={match}
    styles={{
        borderRadius: "lg",
        shadow: "md",
        padding: "lg",
        typography: {
            teamName: "text-lg font-bold",
            score: "text-3xl font-black",
        },
    }}
/>

Common Style Options

| Option | Values | | ------------------------ | ------------------------------------------------------------------ | | borderRadius | none | sm | md | lg | xl | 2xl | 3xl | full | | shadow / hoverShadow | none | sm | md | lg | xl | 2xl | | padding | none | sm | md | lg | xl | | typography | Tailwind classes for text elements | | background | Custom background classes | | container | Additional container classes |

TypeScript Support

All components are fully typed. Import types as needed:

import type {
    MatchScoreContent,
    MatchScoreProps,
    CardContent,
    CardStyles,
    Competitor,
    MatchSimple,
} from "fansunited-sports-ui";

Browser Support

• Chrome, Firefox, Safari, Edge (latest 2 versions)
• React 18.x or 19.x

License

MIT © Fans United