DEV Community: Marcello Novelli

5 Essential React Hooks to master UI and DOM

Marcello Novelli — Thu, 10 Jul 2025 08:31:45 +0000

Working with the DOM in React can be tricky. You're dealing with responsive layouts, scroll behaviors, hover states, and element measurements - all while keeping your components clean and performant. The good news? There are specialized hooks that make DOM manipulation feel as natural as managing regular state.

These 5 hooks have become my go-to tools for handling UI interactions and DOM-related challenges. They'll help you build responsive, interactive interfaces without the usual headaches of direct DOM manipulation. 🚀

Want to see more hooks?

If you want to see more hooks like these, check out the unlogg/hooks. It has a growing collection of custom hooks that can help you manage UI and DOM interactions more effectively in your React applications.

1. useMediaQuery - Responsive Design Made Easy

See code for: useMediaQuery

Tired of writing CSS media queries and then duplicating the same logic in JavaScript? useMediaQuery brings CSS media query power directly into your React components.

When to use it:

Responsive component rendering
Conditional feature loading
Adapting to user preferences (dark mode, reduced motion)
Device-specific functionality

The Hook:

function useMediaQuery(
  query: string,
  options: {
    defaultValue?: boolean;
    initializeWithValue?: boolean;
  } = {}
): boolean;

Real-world example:

function ResponsiveNavigation() {
  const isMobile = useMediaQuery("(max-width: 768px)");
  const isDarkMode = useMediaQuery("(prefers-color-scheme: dark)");
  const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");

  return (
    <nav className={isDarkMode ? "dark" : "light"}>
      {isMobile ? (
        <MobileMenu />
      ) : (
        <DesktopMenu 
          animated={!prefersReducedMotion}
        />
      )}
    </nav>
  );
}

Why it's awesome: It handles SSR gracefully, respects user preferences, and keeps your responsive logic co-located with your components. No more guessing what breakpoint triggered a re-render!

2. useScrollIntoView - Smooth Scrolling Without the Complexity

See code for: useScrollIntoView

Need to scroll to elements programmatically? useScrollIntoView handles smooth scrolling, respects user preferences, and gives you full control over the behavior.

When to use it:

"Skip to content" links
Form validation (scroll to error)
Step-by-step tutorials
Search result highlighting

The Hook:

function useScrollIntoView<T extends HTMLElement = HTMLElement>(
  options: ScrollIntoViewOptions = {}
): [React.RefObject<T | null>, UseScrollIntoViewReturn];

Real-world example:

function FormWithValidation() {
  const [errorRef, { scrollIntoView }] = useScrollIntoView({
    behavior: "smooth",
    block: "center"
  });

  const handleSubmit = (e) => {
    e.preventDefault();
    const errors = validateForm();

    if (errors.length > 0) {
      // Smoothly scroll to the first error
      scrollIntoView();
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <Input name="email" />
      <div ref={errorRef} className="error">
        {/* Error message appears here */}
      </div>
      <Button type="submit">Submit</Button>
    </form>
  );
}

Smart feature: It automatically respects prefers-reduced-motion settings, falling back to instant scrolling when users prefer less motion. Accessibility built-in!

3. useHover - Interactive UI Made Simple

See code for: useHover

Hover states are everywhere in modern UIs. useHover makes detecting hover states clean and reusable, without the usual event listener boilerplate.

When to use it:

Tooltips and popovers
Interactive cards
Button hover effects
Conditional content display

The Hook:

function useHover<T extends HTMLElement = HTMLElement>(
  elementRef: React.RefObject<T | null>
): boolean;

Real-world example:

function InteractiveCard() {
  const hoverRef = useRef(null);
  const isHovered = useHover(hoverRef);

  return (
    <div
      ref={hoverRef}
      className={`card ${isHovered ? "elevated" : ""}`}
    >
      <h3>Product Name</h3>
      <p>Product description...</p>

      {/* Only show actions on hover */}
      {isHovered && (
        <div className="actions">
          <Button>Add to Cart</Button>
          <Button variant="outline">View Details</Button>
        </div>
      )}
    </div>
  );
}

Performance tip: Unlike CSS :hover, this hook lets you conditionally render expensive components only when needed, keeping your app snappy.

4. useElementSize - Responsive Components That Actually Respond

See code for: useElementSize

Container queries are the future, but useElementSize brings element-based responsive design to React today. Track any element's dimensions and respond to changes in real-time.

When to use it:

Container-based responsive design
Canvas or SVG sizing
Dynamic layout calculations
Responsive text sizing

The Hook:

function useElementSize<T extends HTMLElement = HTMLDivElement>(): [
  React.RefObject<T | null>,
  ElementSize
];

Real-world example:

function AdaptiveChart() {
  const [containerRef, { width, height }] = useElementSize();

  // Adjust chart complexity based on available space
  const showDetails = width > 600;
  const showLegend = height > 400;

  return (
    <div ref={containerRef} className="chart-container">
      <Chart
        width={width}
        height={height}
        showDetails={showDetails}
        showLegend={showLegend}
        data={chartData}
      />

      {width > 0 && (
        <p className="size-info">
          Container: {width} × {height}
        </p>
      )}
    </div>
  );
}

Real-world win: Perfect for creating truly adaptive components that respond to their container size, not just the viewport. Your charts, grids, and complex layouts will thank you.

5. useMobile - Mobile Detection Done Right

See code for: useMobile

Mobile detection sounds simple, but it's full of edge cases. useMobile handles SSR, custom breakpoints, and provides a clean API for mobile-specific logic.

When to use it:

Mobile-specific features
Touch vs mouse interactions
Performance optimizations
Progressive enhancement

The Hook:

function useMobile(
  breakpoint: number = 768,
  options: UseMobileOptions = {}
): boolean;

Real-world example:

function ImageGallery() {
  const isMobile = useMobile(768, {
    defaultValue: false, // SSR-friendly
    initializeWithValue: false
  });

  return (
    <div className="gallery">
      {isMobile ? (
        // Mobile: Touch-friendly carousel
        <TouchCarousel images={images} />
      ) : (
        // Desktop: Hover-based grid
        <GridWithHover images={images} />
      )}

      {/* Mobile-specific features */}
      {isMobile && (
        <SwipeHint>Swipe to see more images</SwipeHint>
      )}
    </div>
  );
}

SSR-friendly: Unlike naive window.innerWidth checks, this hook handles server-side rendering gracefully and won't cause hydration mismatches.

Putting It All Together

Here's how these hooks work together in a real component:

function SmartWidget() {
  const [widgetRef, { width }] = useElementSize();
  const hoverRef = useRef(null);
  const isHovered = useHover(hoverRef);
  const isMobile = useMobile();
  const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
  const [scrollTarget, { scrollIntoView }] = useScrollIntoView();

  const isCompact = width < 300;

  return (
    <div ref={widgetRef}>
      <div
        ref={hoverRef}
        className={`widget ${isHovered && !isMobile ? "hover" : ""}`}
      >
        <h3>Smart Widget</h3>

        {/* Responsive content based on actual size */}
        {isCompact ? (
          <CompactView />
        ) : (
          <FullView />
        )}

        {/* Mobile-specific interactions */}
        {isMobile ? (
          <TouchControls />
        ) : (
          <MouseControls />
        )}

        {/* Hover-based actions */}
        {isHovered && !isMobile && (
          <ActionButtons
            animated={!prefersReducedMotion}
          />
        )}
      </div>

      {/* Scroll target for focus management */}
      <div ref={scrollTarget} />
    </div>
  );
}

Wrapping Up

These 5 hooks solve the most common UI and DOM management challenges you'll face:

useMediaQuery - Responsive design and user preferences
useScrollIntoView - Smooth, accessible scrolling
useHover - Clean hover state management
useElementSize - True container-based responsive design
useMobile - Reliable mobile detection

Each hook handles the edge cases, performance concerns, and accessibility requirements that you'd otherwise have to implement yourself. They're the building blocks for creating polished, responsive, and accessible user interfaces.

Get more hooks!

The DOM doesn't have to be scary in React - these hooks make it feel like just another piece of state to manage. Happy coding! 🚀

Deploy a Docker app to Digital Ocean App Platform + Prisma migrations

Marcello Novelli — Fri, 04 Jul 2025 06:41:59 +0000

One of the challenges of deploying a Dockerized Node.js application is managing database migrations, especially when using an ORM like Prisma. In this guide, we'll explore how to deploy such an application on Digital Ocean's App Platform while ensuring that Prisma migrations are handled correctly.

We'll cover database setup, app deployment, and automated migrations.

Let's get started!

Prerequisites

Before starting, ensure you have:

A Docker image pushed to Docker Hub (public or private)
A Digital Ocean account
Basic knowledge of Docker and Prisma

1. Set up a Database Cluster

First, let's create a managed PostgreSQL database:

Navigate to Managed Databases in your Digital Ocean dashboard
Create a new database cluster:
- Choose the lowest tier for cost optimization
- Select PostgreSQL as the database type
Important: Do not add "Trusted Sources" yet, as this will prevent the API service from connecting during the initial deployment
Copy the connection string from the cluster settings - you'll need this later
Wait a few minutes for the cluster to become ready before proceeding

Note: We'll secure the database with trusted sources later in the process.

2. Deploy Your App via App Platform

Create the Application

Go to App Platform and click Create App
Choose Deploy from a container registry
Select Docker Hub as your registry
Configure your container:
- Image name: your-docker-username/your-app-name:latest
- Authentication: Only required for private repositories (use username and token)

Configure Environment Variables

Set up your environment variables:

SERVER_URL: Use the dynamic variable ${APP_URL}
DATABASE_URL: Paste the connection string from your database cluster
Add any other required environment variables

Set the Correct Port

Change the default port to match your application's configuration (e.g., port 5001).

Click Save to deploy your application.

3. Handle Database Migrations

After deployment, your app will start successfully, but any Prisma-dependent endpoints will fail because the database tables don't exist yet. You have several options to handle migrations:

Option A: Manual Migrations ❌

Manually connecting to the database to run migrations is not recommended for production environments.

Option B: Auto-migrations on App Start ⚠️

While you could modify your Dockerfile to run migrations on startup, this approach has drawbacks:

Race conditions: Multiple instances might try to run migrations simultaneously
Scaling issues: Not suitable for horizontally scaled applications
Production concerns: Even with Prisma's migration locks, this isn't ideal for production

Option C: Separate Migration Service ✅ Recommended

Create a dedicated migration job that runs before your app starts.

4. Create a Migration Job

Add the Migration Job

Go back to your App Platform application
Click Add Resources → Create resources from source code
Choose Container Image and select Jobs
Configure the job:
- Image: Use the same Docker image as your main app
- Tier: Choose the cheapest option (migrations are lightweight)
- Environment Variables: Add DATABASE_URL with your database connection string

Configure Job Trigger

In the Job Trigger section:

Select Before every deploy
Build command: Override the default Dockerfile command with:

  npx prisma migrate deploy

This command tells Digital Ocean to run Prisma migrations instead of starting the application.

Click Save to create the job.

5. Final Deployment

Digital Ocean will now redeploy your application with the following sequence:

Migration job runs first: Applies any pending database migrations
Main app starts: Only after migrations complete successfully
Failure handling: If migrations fail, the deployment stops and the app won't start

Monitor the deployment logs to verify everything works correctly.

6. Test Your Application

Health Check

Test the basic functionality:

GET /api/health

Expected response: 200 OK with a success message.

Database Operations

Try creating a new user or performing other database operations to confirm Prisma is working correctly.

7. Secure Database Connection (Recommended)

Attach Database to App

In App Platform, go to your application
Click Add Resources → Create or attach Database
Select Attach existing DO database
Choose your running database cluster
Select the appropriate database name and user
Add the API app as a trusted source
Click Attach Database

Update Environment Variables

After the deployment completes:

Main App: Replace the hardcoded DATABASE_URL with the dynamic variable:

   ${db-postgresql-nyc3-25166.DATABASE_URL}

Migration Job: Update the DATABASE_URL environment variable with the same dynamic reference

This setup provides:

✅ Secure database connections
✅ Automated migrations
✅ Proper separation of concerns
✅ Production-ready deployment pipeline

Important Notes

Environment Variables: Digital Ocean environment variables don't include trailing slashes
- Example: CLIENT_URL = "https://your-app.pages.dev"
Consistency: Apply the same URL format when setting VITE_SERVER_URL in other platforms like Cloudflare

Conclusion

You now have a fully functional Digital Ocean setup with:

A running API service
Managed PostgreSQL database with secure connections
Automated migration capabilities
Production-ready deployment pipeline

This architecture ensures your database schema stays synchronized with your application deployments while maintaining security and reliability.

5 Essential React Hooks to Master State Management

Marcello Novelli — Thu, 03 Jul 2025 08:38:11 +0000

5 Essential React Hooks to Master State Management

I love react hooks and use them all the time. While useState and useEffect are the bread and butter, there are specialized hooks that can make your state management much more elegant and powerful. These are 5 hooks that I find myself using in almost every project, and they can help you write cleaner, more maintainable code.

Want to see more hooks?

If you want to see more hooks like these, check out the unlogg/hooks. It has a growing collection of custom hooks that can help you manage state more effectively in your React applications.

1. useDisclosure - Your Modal's Best Friend

See code for: useDisclosure

Ever found yourself writing the same open/close logic for modals, dropdowns, or any toggle-based UI? useDisclosure is here to save the day.

When to use it:

Modals and dialogs
Dropdown menus
Collapsible sections
Any on/off state with callbacks

The Hook:

function useDisclosure(
  initialState: boolean = false,
  options: { onOpen?: () => void; onClose?: () => void } = {}
): [boolean, { open: () => void; close: () => void; toggle: () => void }];

Real-world example:

function MyModal() {
  const [opened, { open, close, toggle }] = useDisclosure(false, {
    onOpen: () => console.log("Modal opened!"),
    onClose: () => console.log("Modal closed!"),
  });

  return (
    <div>
      <Button onClick={open}>Open Modal</Button>
      <Dialog open={opened} onOpenChange={opened ? close : open}>
        <DialogContent>
          <h2>Hello World!</h2>
          <Button onClick={close}>Close</Button>
          <Button onClick={toggle}>Toggle</Button>
        </DialogContent>
      </Dialog>
    </div>
  );
}

Why it's awesome: No more forgetting to add onOpen callbacks or accidentally creating infinite re-renders. The hook handles all the edge cases for you.

2. useStateHistory - Time Travel for Your State

See code for: useStateHistory

Want to add undo/redo functionality without the complexity? useStateHistory gives you time-travel powers for any state value.

When to use it:

Text editors with undo/redo
Drawing applications
Form wizards
Any app where users might want to revert changes

The Hook:

function useStateHistory<T>(
  initialValue: T,
  options: { maxHistorySize?: number } = {}
): [
  T,
  {
    setValue: (value: T | ((prev: T) => T)) => void;
    back: () => void;
    forward: () => void;
    canGoBack: boolean;
    canGoForward: boolean;
    history: T[];
  },
];

Real-world example:

function CounterWithHistory() {
  const [count, { setValue, back, forward, canGoBack, canGoForward }] =
    useStateHistory(0, { maxHistorySize: 10 });

  return (
    <div>
      <h2>Count: {count}</h2>
      <Button onClick={() => setValue((prev) => prev + 1)}>+1</Button>
      <Button onClick={() => setValue((prev) => prev - 1)}>-1</Button>

      <Button onClick={back} disabled={!canGoBack}>
        ← Undo
      </Button>
      <Button onClick={forward} disabled={!canGoForward}>
        Redo →
      </Button>
    </div>
  );
}

Pro tip: The hook automatically manages memory by limiting history size, so you don't have to worry about memory leaks in long-running apps.

3. useLocalStorage - Persistent State Made Simple

See code for: useLocalStorage

Tired of losing user preferences on page refresh? useLocalStorage makes state persistence as easy as regular useState.

When to use it:

User preferences (theme, language)
Shopping cart contents
Form draft saving
Any state that should survive browser sessions

The Hook:

function useLocalStorage<T>({
  key: string;
  defaultValue: T;
}): [T, (value: T) => void]

Real-world example:

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage({
    key: "user-theme",
    defaultValue: "dark",
  });

  const toggleTheme = () => {
    setTheme(theme === "dark" ? "light" : "dark");
  };

  return (
    <div className={`app ${theme}`}>
      <Button onClick={toggleTheme}>
        Switch to {theme === "dark" ? "Light" : "Dark"} mode
      </Button>
    </div>
  );
}

The magic: It handles SSR gracefully, manages JSON serialization, and provides error handling out of the box. Your state just works™.

4. useDebounceValue - Performance Optimization Without the Headache

See code for: useDebounceValue

Search boxes, API calls, expensive calculations - useDebounceValue prevents your app from choking on rapid updates.

When to use it:

Search inputs
API calls triggered by user input
Expensive calculations
Auto-save functionality

The Hook:

function useDebounceValue<T>(
  initialValue: T,
  delay: number,
  options: { onDebounce?: (value: T) => void } = {}
): [T, { setValue: (val: T) => void }];

Real-world example:

function SearchBox() {
  const [query, setQuery] = useState("");
  const [debouncedQuery, { setValue }] = useDebounceValue("", 300, {
    onDebounce: (value) => {
      if (value) {
        // This only fires 300ms after user stops typing
        fetchSearchResults(value);
      }
    },
  });

  useEffect(() => {
    setValue(query);
  }, [query, setValue]);

  return (
    <div>
      <Input
        placeholder="Search..."
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <p>Searching for: {debouncedQuery}</p>
    </div>
  );
}

Performance win: Instead of making 10 API calls as someone types "javascript", you make just 1 call 300ms after they finish.

5. Bonus: useToggle - The Simplest State Hook

See code for: useToggle

Sometimes you just need a boolean that flips. useToggle is the minimalist's dream.

When to use it:

Show/hide toggles
Feature flags
Simple boolean switches

Quick implementation:

function useToggle(initialValue: boolean = false) {
  const [value, setValue] = useState(initialValue);
  const toggle = useCallback(() => setValue((v) => !v), []);
  return [value, toggle, setValue] as const;
}

Usage:

function FeatureToggle() {
  const [isEnabled, toggle] = useToggle(false);

  return (
    <Button onClick={toggle}>Feature is {isEnabled ? "ON" : "OFF"}</Button>
  );
}

Wrapping Up

These 5 hooks solve common state management patterns that you'll encounter in almost every React app:

useDisclosure - Clean modal/toggle state
useStateHistory - Undo/redo functionality
useLocalStorage - Persistent state across sessions
useDebounceValue - Performance optimization for rapid updates
useToggle - Simple boolean state management

Get more hooks!

If you want to see more hooks like these, check out the unlogg/hooks. It has a growing collection of custom hooks that can help you manage state more effectively in your React applications.

How to build a MCP (model context protocol) server for UI libraries + repo

Marcello Novelli — Thu, 26 Jun 2025 11:35:31 +0000

Introduction

The Model Context Protocol (MCP) represents a paradigm shift in how AI assistants interact with external data sources and tools. Developed by Anthropic, MCP enables AI models like Claude to seamlessly access and utilize external resources through standardized server implementations. This creates powerful workflows where AI can directly interact with your UI component libraries, documentation, and tools.

For UI library maintainers and design system creators, MCP opens up unprecedented opportunities. Imagine an AI assistant that can instantly understand your component library structure, provide implementation details, suggest appropriate components based on context, and even help developers implement designs using your exact components.

In this guide, we'll walk through building a complete MCP server tailored for UI libraries.

Example Repo 👨‍💻

For a complete example implementation, including all the code discussed in this article, please refer to the mcp-starter repository available on GitHub.

Understanding the Model Context Protocol

What is MCP?

The Model Context Protocol is a standardized way for AI assistants to communicate with external services and data sources.

Think of it as an API specifically designed for AI consumption. Unlike traditional REST APIs that return data for human consumption, MCP servers provide structured data and tools that AI models can understand and utilize effectively.

MCP servers expose a set of tools that AI models can invoke, allowing them to fetch data, perform actions, and interact with external systems in a way that is context-aware and intelligent.

Why MCP for UI Libraries?

UI libraries face unique challenges in AI integration:

Component Discovery: Developers often struggle to find the right component for their needs
Implementation Guidance: Understanding component props, usage patterns, and best practices
Context-Aware Suggestions: Recommending components based on design context
Code Generation: Generating proper implementation code with correct imports and usage

MCP addresses these challenges by providing AI models with direct access to your component registry, enabling intelligent recommendations and code generation.

The Registry Format Foundation

Many modern UI libraries follow the "registry" format popularized by shadcn/ui. This format provides:

Structured Component Definitions: JSON files describing each component
Standardized Metadata: Type information, descriptions, and dependencies
Version Control: Trackable changes and updates
CLI Integration: Easy installation and updates

Our MCP server leverages this existing structure, making it ideal for libraries already following this pattern.
Learn more about the registry format in the shadcn/ui documentation.

Project Architecture Overview

Before diving into implementation, let's understand the architecture of our MCP server:

mcp-server/
├── src/
│   ├── server.ts              # Main MCP server implementation
│   ├── lib/
│   │   ├── config.ts          # Configuration settings
│   │   └── categories.ts      # Component organization
│   └── utils/
│       ├── api.ts             # Registry API interactions
│       ├── schemas.ts         # Data validation
│       ├── formatters.ts      # Data transformation
│       └── index.ts           # Utility exports
├── package.json               # Dependencies and scripts
└── tsconfig.json             # TypeScript configuration

This architecture separates concerns cleanly:

Server Layer: Handles MCP protocol communication
Configuration Layer: Manages project-specific settings
API Layer: Fetches and processes registry data
Validation Layer: Ensures data integrity
Transformation Layer: Formats data for AI consumption

You can of couse extend this architecture as needed, adding new utilities, categories, or API endpoints to suit your specific requirements.
This is just a starting point to get you going.

Step-by-Step Implementation

Step 1: Project Setup and Dependencies

First, let's understand why we need each dependency:

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.13.1",
    "zod": "^3.25.67"
  },
  "devDependencies": {
    "@modelcontextprotocol/inspector": "^0.14.2",
    "@types/node": "^22.14.1",
    "tsup": "^8.5.0",
    "tsx": "^4.20.3",
    "typescript": "^5.8.3"
  }
}

Why these dependencies?

@modelcontextprotocol/sdk: The core SDK for building MCP servers. It handles protocol communication, request/response formatting, and transport management.
zod: Runtime type validation. Essential for ensuring data integrity when fetching from external registries.
@modelcontextprotocol/inspector: Development tool for testing MCP servers interactively.
tsup: Fast TypeScript bundler optimized for Node.js applications.
tsx: TypeScript execution with hot reloading for development.

Step 2: Configuration Management

Configuration is crucial for making your MCP server adaptable. I like to keep everything in one file so here's our configuration structure:

// src/lib/config.ts
export const mcpConfig = {
  projectName: "your-ui-library",
  baseUrl: "https://your-ui-library.com",
  registryUrl: "https://your-ui-library.com/r",
  registryFileUrl: "https://your-ui-library.com/registry.json",
};

The configuration assumes your registry follows this URL structure:

Registry Index: /registry.json - Lists all available components
Component Details: /r/{component-name}.json - Individual component implementations

Step 3: Data Validation with Zod Schemas

I use zod for validation to ensure that all data fetched from the registry adheres to expected formats. This is an example of the schemas we will use:

// src/utils/schemas.ts
import { z } from "zod";

export const ComponentSchema = z.object({
  name: z.string(),
  type: z.string(),
  description: z.string().optional(),
});

export const ComponentDetailSchema = z.object({
  name: z.string(),
  type: z.string(),
  files: z.array(
    z.object({
      content: z.string(),
    })
  ),
});

export const IndividualComponentSchema = ComponentSchema.extend({
  install: z.string(),
  content: z.string(),
  examples: z.array(
    z.object({
      name: z.string(),
      type: z.string(),
      description: z.string(),
      content: z.string(),
    })
  ),
});

We will use these schemas later when fetching and processing component data.

Step 4: API Layer Implementation

We then create the API layer that interacts with our component registry. This layer fetches component data, validates it, and prepares it for use by the MCP server.

The API layer handles all interactions with your component registry:

// src/utils/api.ts
import { mcpConfig } from "../lib/config.js";
import { ComponentDetailSchema, ComponentSchema } from "./schemas.js";

export async function fetchUIComponents() {
  try {
    const response = await fetch(mcpConfig.registryFileUrl);
    if (!response.ok) {
      throw new Error(`Failed to fetch registry: ${response.statusText}`);
    }
    const data = await response.json();

    return data.registry
      .filter((item: any) => item.type === "registry:component")
      .map((item: any) => {
        try {
          return ComponentSchema.parse(item);
        } catch (parseError) {
          console.error(`Invalid component data for ${item.name}:`, parseError);
          return null;
        }
      })
      .filter(Boolean);
  } catch (error) {
    console.error("Error fetching components:", error);
    return [];
  }
}

export async function fetchComponentDetails(componentName: string) {
  try {
    const response = await fetch(
      `${mcpConfig.registryUrl}/${componentName}.json`
    );
    if (!response.ok) {
      throw new Error(
        `Failed to fetch component ${componentName}: ${response.statusText}`
      );
    }
    const data = await response.json();
    return ComponentDetailSchema.parse(data);
  } catch (error) {
    console.error(`Error fetching component ${componentName}:`, error);
    throw error;
  }
}

This API layer provides two main functions:

fetchUIComponents: Retrieves the list of all components from the registry
fetchComponentDetails: Fetches detailed implementation data for a specific component

You can extend this layer to include additional API endpoints as needed, such as fetching specific categories or related components.

Step 5: Component Organization and Categories

To make it easier for AI models to find and use components, we categorize them based on their functionality. This is especially important for large libraries where a flat list of components would be unwieldy. Also, some AI models and IDEs have limits on the number of tools they can handle, so categorizing helps to keep the number of tools manageable.

For example, we can define categories like "Buttons", "Forms", "Navigation", and "Data Display":

// src/lib/categories.ts
export const componentCategories = {
  Buttons: [
    "button-primary",
    "button-secondary",
    "button-ghost",
    "button-outline",
  ],
  Forms: ["input-text", "input-email", "textarea", "select", "checkbox"],
  Navigation: ["navbar", "sidebar", "breadcrumbs", "pagination"],
  DataDisplay: ["table", "card", "badge", "avatar", "tooltip"],
};

The way you define categories can vary based on your component library's structure and the needs of your users. The key is to create logical groupings that make sense for developers looking to implement UI components.

Step 6: Data Transformation and Formatting

We add a formatter function to format the component names and generate installation instructions. This preparares the data for AI consumption, ensuring that the AI models receive consistent and actionable information.

This is also where you could add any additional formatting or transformation logic needed for your specific use case, such as generating import statements or usage examples.

// src/utils/formatters.ts
export function formatComponentName(componentName: string): string {
  return componentName
    .split("-")
    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
    .join("");
}

export function generateInstallInstructions(componentName: string): string {
  const formattedName = formatComponentName(componentName);
  return `You can install the component using shadcn/ui CLI:

  npx shadcn@latest add "${mcpConfig.registryUrl}/${componentName}.json"

  Once installed, import it like this:
  import { ${formattedName} } from "@/components/ui/${componentName}";`;
}

Step 7: Core MCP Server Implementation

Now we implement the main server logic.

Since we are using the MCP SDK, creating the server is straightforward. The server will handle incoming requests, invoke tools, and return structured responses that AI models can understand.

All you need to do to create a basic MCP server is to initialize the McpServer class and connect it to a transport layer. In this case, we will use the StdioServerTransport, which allows the server to communicate over standard input/output streams.

MCP SDK supports other transports. Please refer to the MCP SDK documentation for more details.

// src/server.ts
#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { fetchUIComponents, fetchComponentDetails } from "./utils/index.js";
import { componentCategories } from "./lib/categories.js";

// Initialize the MCP Server
const server = new McpServer({
  name: "your-ui-library-mcp",
  version: "1.0.0",
});

This initializes the MCP server with a name and version. You can customize these values to match your project.

Step 8: Implementing MCP Tools

Ok, now that we have a MCP server, we can start implementing tools that AI models can invoke. Tools are the core functionality that allows AI models to interact with your component library.

As already mentioned, this step can vary dramatically based on your specific use cases.

In this example, we will register a tool to fetch all UI components and another tool for each category of components.
This allows AI models to discover all components and understand their usage.

// Main tool for getting all components
server.tool(
  "getUIComponents",
  "Provides a comprehensive list of all UI components.",
  {},
  async () => {
    try {
      const uiComponents = await fetchUIComponents();
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(uiComponents, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to fetch components",
          },
        ],
        isError: true,
      };
    }
  }
);

What this code is doing is essentially registering a tool named getUIComponents that AI models can invoke. When called, it fetches all UI components from the registry and returns them in a structured format.

Step 9: Dynamic Category Tool Generation

Now that we have a generic tool for fetching all components, we can dynamically generate more "specialized" tools for each category defined in componentCategories. This allows AI models to access specific groups of components without overwhelming them with too many options.

async function registerComponentsCategoryTools() {
  const [components, allExampleComponents] = await Promise.all([
    fetchUIComponents(),
    fetchExampleComponents(),
  ]);

  for (const [category, categoryComponents] of Object.entries(
    componentCategories
  )) {
    const componentNamesString = categoryComponents.join(", ");

    server.tool(
      `get${category}`,
      `Provides implementation details for ${componentNamesString} components.`,
      {},
      async () => {
        try {
          const categoryResults = await fetchComponentsByCategory(
            categoryComponents,
            components,
            exampleNamesByComponent
          );

          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(categoryResults, null, 2),
              },
            ],
          };
        } catch (error) {
          return {
            content: [
              { type: "text", text: `Error processing ${category} components` },
            ],
            isError: true,
          };
        }
      }
    );
  }
}

This function registers a tool for each category defined in componentCategories. Each tool fetches the relevant components and returns their details in a structured format.

This dynamic registration allows you to easily add or remove categories without changing the core server logic.

Step 10: Advanced Component Processing

The component processing logic handles the complex task of enriching component data.

It fetches detailed implementation data, generates installation instructions, and formats the content for AI consumption. This is where we ensure that AI models receive all necessary context to understand and use the components effectively.

Also, with zod, we can validate the data at runtime to ensure it adheres to our expected schemas.

async function fetchComponentsByCategory(
  categoryComponents: string[],
  allComponents: any[],
  exampleNamesByComponent: Map<string, string[]>
) {
  const componentResults = [];

  for (const componentName of categoryComponents) {
    const component = allComponents.find((c) => c.name === componentName);
    if (!component) continue;

    try {
      const componentDetails = await fetchComponentDetails(componentName);
      const componentContent = componentDetails.files[0]?.content;

      const installInstructions = generateInstallInstructions(componentName);
      const disclaimerText = generateDisclaimerText(componentName);

      const validatedComponent = IndividualComponentSchema.parse({
        name: component.name,
        type: component.type,
        description: component.description,
        install: installInstructions,
        content: componentContent && disclaimerText + componentContent,
        examples: formattedExamples,
      });

      componentResults.push(validatedComponent);
    } catch (error) {
      console.error(`Error processing component ${componentName}:`, error);
    }
  }

  return componentResults;
}

Step 11: Server Lifecycle Management

As one of the final steps, we need to create a function to start the server and handle any errors gracefully. This ensures that even if some components fail to load, the server can still operate with limited functionality and / or provide useful error messages.

async function startServer() {
  try {
    // Initialize category tools first
    await registerComponentsCategoryTools();

    // Connect to stdio transport
    const transport = new StdioServerTransport();
    await server.connect(transport);

    console.log("✅ MCP server started successfully");
  } catch (error) {
    console.error("❌ Error starting MCP server:", error);

    // Try to start server anyway with basic functionality
    try {
      const transport = new StdioServerTransport();
      await server.connect(transport);
      console.error("⚠️ MCP server started with limited functionality");
    } catch (connectionError) {
      console.error("❌ Failed to connect to transport:", connectionError);
      process.exit(1);
    }
  }
}

// Start the server
startServer();

Development and Testing

Now that we have a basic MCP server implementation, let's discuss how to develop and test it effectively.

Development Workflow

The project includes several development scripts:

{
  "scripts": {
    "build": "tsup src/server.ts --format esm,cjs --dts --out-dir dist",
    "dev": "tsx watch src/server.ts",
    "inspect": "mcp-inspector node dist/server.js",
    "start": "node dist/server.js"
  }
}

Using the MCP Inspector

One of fastest and easiest way to test your MCP server is to use the MCP Inspector. This tool provides a web interface for interacting with your MCP server, allowing you to invoke tools, view responses, and debug issues.

If you install the inspector as a dev dependency, you can run it with:

pnpm run inspect

Or if you prefer to run it without installing, you can use:

npx mcp-inspector

This opens a web interface where you can:

Test Tools: Invoke tools with different parameters
View Responses: See exactly what AI models receive
Debug Errors: Identify issues in tool implementations
Validate Schema: Ensure data matches expected formats

Testing Your Implementation

Before deploying, test your MCP server thoroughly:

Component Discovery: Verify all components are found
Category Tools: Test each category tool individually
Error Handling: Test with invalid component names
Performance: Check response times with large component libraries
Data Integrity: Validate all returned data matches schemas

Deployment and Integration

Local Development Setup

For local development with Claude Desktop:

Build the server:

pnpm run build

Configure Claude Desktop (~/.config/Claude Desktop/claude_desktop_config.json):

{
  "mcpServers": {
    "your-ui-library": {
      "command": "node",
      "args": ["/absolute/path/to/your/dist/server.js"]
    }
  }
}

Restart Claude Desktop to load the new server

Production Deployment

For production deployment, consider:

NPM Package: Publish as an NPM package for easy installation
Docker Container: Containerize for consistent deployment
Server Hosting: Deploy on cloud platforms for remote access
CI/CD Integration: Automate builds and deployments

Configuration Management

In production, externalize configuration:

export const mcpConfig = {
  projectName: process.env.PROJECT_NAME || "your-ui-library",
  baseUrl: process.env.BASE_URL || "https://your-ui-library.com",
  registryUrl: process.env.REGISTRY_URL || "https://your-ui-library.com/r",
  registryFileUrl:
    process.env.REGISTRY_FILE_URL ||
    "https://your-ui-library.com/registry.json",
};

Conclusion

Building an MCP server for UI libraries represents a significant leap forward in how developers can interact with component systems. By providing AI assistants with direct access to your component registry, you enable intelligent recommendations, automated code generation, and contextual guidance that dramatically improves the developer experience.

Example Repo

For a complete example implementation, including all the code discussed in this article, please refer to the mcp-starter repository.

References and Further Reading

Awknowledgments

This was originally inspired by Magic UI MCP Server.

Better GraphQL Error Handling with Typed Union Responses

Marcello Novelli — Mon, 16 Jun 2025 06:05:21 +0000

Unlike traditional REST APIs that leverage HTTP status codes (404 for not found, 400 for validation errors, 500 for server errors), GraphQL typically returns a 200 status code with all responses, whether successful or not, embedding errors within the response payload.

The standard GraphQL error handling approach often results in generic error messages that lack the rich context needed for proper client-side error handling, making it difficult to create user-friendly applications with meaningful error feedback.

In this post, we'll explore an elegant and comprehensive solution to GraphQL error handling by treating errors as first-class citizens in our schema. We'll demonstrate how to type errors as GraphQL types and use union types to create predictable, type-safe error responses that provide rich context and enable excellent developer and user experiences.

Just show me the code 💻:

If you want to see how I implemented this, please check this starter graphql template on my github

The Challenge with Traditional GraphQL Error Handling

Before diving into the solution, let's examine the common approaches to error handling in GraphQL and understand why they fall short of providing an optimal developer experience.

1. Generic Error Responses

The most common approach is relying on GraphQL's built-in error handling mechanism. When a resolver throws an error, GraphQL catches it and returns it in the errors array alongside the data:

{
  "data": {
    "createTodo": null
  },
  "errors": [
    {
      "message": "Todo with this title already exists",
      "locations": [{"line": 2, "column": 3}],
      "path": ["createTodo"]
    }
  ]
}

While this works, it has several limitations:

Unpredictable structure: Clients can't know what properties an error might have
No type safety: TypeScript can't help with error handling since the structure is unknown
Generic handling: All errors look the same, making it hard to provide specific user feedback

2. Exception-Based Error Handling

Another common pattern is throwing exceptions in resolvers:

const createTodo = async (_, { input }) => {
  if (!input.title) {
    throw new Error("Title is required");
  }

  const existingTodo = await findTodoByTitle(input.title);
  if (existingTodo) {
    throw new Error("Todo already exists");
  }

  return await createNewTodo(input);
};

This approach has similar problems:

Loss of error context: Important details about the error are lost
Inconsistent error codes: No standardized way to categorize errors
Poor client experience: Clients receive generic error messages without context

3. Field-Level Nullability with Error Fields

Some developers try to solve this by making fields nullable and adding error fields:

type Mutation {
  createTodo(input: TodoInput!): TodoResponse
}

type TodoResponse {
  todo: Todo
  error: String
}

While this provides some structure, it still has issues:

Weak typing: Error information is just a string
Inconsistent patterns: Different mutations might handle errors differently
No error categorization: Can't distinguish between validation, authorization, or server errors

The Root Problem

All these approaches share a fundamental issue: they treat errors as second-class citizens in the GraphQL schema. Errors lack the rich typing and structure that make GraphQL so powerful for regular data. This results in:

Lack of type safety: Clients can't predict what error types they might receive
Poor client experience: Generic error messages don't provide enough context for proper error handling
Difficult testing: Without predictable error structures, it's hard to test error scenarios comprehensively
Inconsistent error handling: Different resolvers might handle similar errors differently
Poor developer experience: No IDE autocompletion or compile-time checks for error handling

The Solution: Typed Error Responses with Union Types

Now that we understand the limitations of traditional approaches, let's explore a more robust solution. The key insight is to treat errors as first-class citizens in our GraphQL schema by defining them as proper GraphQL types and using union types to represent all possible outcomes of an operation.

This approach transforms error handling from an afterthought into a core part of your API design. Instead of relying on generic error structures, we create specific, typed error responses that provide rich context and enable type-safe error handling throughout the entire stack.

Step 1: Designing the Error Type Hierarchy

The foundation of our approach is creating a well-structured hierarchy of error types. We start with a base Error interface that defines common properties all errors should have, then create specific error types for different categories of failures.

The Base Error Interface

interface Error {
  message: String!
  code: String!
}

The interface establishes a contract that all error types must follow:

message: A human-readable description of the error
code: A machine-readable error code for programmatic handling

Specific Error Type Implementations

Now we can create specific error types that implement this interface while adding context relevant to their particular error category:

type ValidationError implements Error {
  message: String!
  code: String!
  field: String      # Which field failed validation
}

type NotFoundError implements Error {
  message: String!
  code: String!
  resourceId: ID!    # The ID that wasn't found
  resourceType: String!  # The type of resource (e.g., "Todo", "User")
}

type UnauthorizedError implements Error {
  message: String!
  code: String!
  operation: String!  # What operation was attempted
}

type ServerError implements Error {
  message: String!
  code: String!
  details: String    # Additional debug information
}

type ConflictError implements Error {
  message: String!
  code: String!
  conflictingField: String  # Which field caused the conflict
}

Each error type includes fields that provide specific context for that type of failure:

ValidationError: Includes the field that failed validation, enabling targeted error messages
NotFoundError: Specifies what resource wasn't found and its type, helpful for debugging
UnauthorizedError: Indicates what operation was attempted, useful for permission debugging
ServerError: Provides additional details for debugging while keeping sensitive info from clients
ConflictError: Identifies which field caused the conflict, enabling specific user guidance

Step 2: Creating Union Types for Operations

With our error types defined, we can now create union types that represent all possible outcomes of our GraphQL operations. These unions combine success types (our actual data) with all relevant error types:

union TodoResult = 
  | Todo                # Success case
  | ValidationError     # Invalid input data
  | NotFoundError       # Referenced resource not found
  | ServerError         # Database or server issues
  | ConflictError       # Duplicate data conflicts
  | UnauthorizedError   # Permission issues

union CategoryResult = 
  | Category            # Success case
  | ValidationError     # Invalid input data
  | NotFoundError       # Referenced resource not found
  | ServerError         # Database or server issues
  | ConflictError       # Duplicate data conflicts
  | UnauthorizedError   # Permission issues

These union types serve as contracts between your API and clients, explicitly declaring all possible outcomes. This approach provides several immediate benefits:

Explicit error handling: Clients must handle all possible error types
Type safety: TypeScript can enforce comprehensive error handling
Self-documenting: The schema clearly shows what can go wrong
Consistent patterns: All operations follow the same error handling approach

Step 3: Updating Operation Signatures

Now we update our GraphQL operations to use these union types instead of returning nullable fields:

type Mutation {
  createTodo(todo: TodoCreateInput!): TodoResult!
  updateTodo(todo: TodoUpdateInput!): TodoResult!
  deleteTodo(id: ID!): TodoResult!

  createCategory(category: CategoryCreateInput!): CategoryResult!
  updateCategory(category: CategoryUpdateInput!): CategoryResult!
  deleteCategory(id: ID!): CategoryResult!
}

type Query {
  todoById(id: ID!): TodoResult!
  categoryById(id: ID!): CategoryResult!
}

Notice that all operations now return non-nullable union types. This is a key improvement over traditional approaches where operations might return null or throw exceptions. With union types, every operation has a guaranteed response structure, but the content varies based on success or failure.

Step 4: Implementing Server-Side Resolver Logic

With our schema defined, let's implement the server-side logic that makes this error handling approach work in practice. The key is creating utility functions for consistent error creation and implementing resolvers that use these utilities.

Creating Error Utility Functions

First, we create utility functions that ensure consistent error creation across all resolvers:

// Error creation utilities with proper typing
export const createValidationError = (error: ZodError): ValidationError => ({
  __typename: "ValidationError",
  message: "Validation failed",
  code: "VALIDATION_ERROR",
  field: error.issues[0]?.path.join('.') || null,
});

export const createNotFoundError = (id: string, type: string): NotFoundError => ({
  __typename: "NotFoundError",
  message: `${type} with id ${id} not found`,
  code: "NOT_FOUND",
  resourceId: id,
  resourceType: type,
});

export const createUnauthorizedError = (operation: string): UnauthorizedError => ({
  __typename: "UnauthorizedError",
  message: `Unauthorized to ${operation}`,
  code: "UNAUTHORIZED",
  operation,
});

export const createConflictError = (
  message: string,
  conflictingField?: string
): ConflictError => ({
  __typename: "ConflictError",
  message,
  code: "CONFLICT",
  conflictingField: conflictingField || null,
});

export const createServerError = (
  message: string,
  details?: string
): ServerError => ({
  __typename: "ServerError",
  message,
  code: "SERVER_ERROR",
  details: details || null,
});

// Utility to add __typename to success responses
export const withTypename = <T, K extends string>(
  obj: T,
  typename: K
): T & { __typename: K } => ({
  ...obj,
  __typename: typename,
});

These utilities serve several important purposes:

Consistency: All errors of the same type have the same structure
Type safety: TypeScript ensures the correct fields are included
Maintainability: Changes to error structure only need to be made in one place
Debugging: The __typename field enables GraphQL to resolve union types correctly

Implementing Comprehensive Resolver Logic

Now let's implement a complete resolver that demonstrates how to handle all the different error scenarios:

export const TodoMutations: MutationResolvers = {
  createTodo: async (_, { todo }, { prisma, user }) => {
    // Step 1: Authentication check
    if (!user?.id) {
      return createUnauthorizedError("create todo");
    }

    try {
      // Step 2: Input validation using Zod
      TodoCreateInputSchema.parse(todo);

      // Step 3: Business logic validation
      const existingTodo = await prisma.todo.findFirst({
        where: { 
          title: todo.title, 
          authorId: user.id 
        }
      });

      if (existingTodo) {
        return createConflictError(
          `A todo with title '${todo.title}' already exists`,
          "title"
        );
      }

      // Step 4: Data creation with proper error handling
      const newTodo = await prisma.todo.create({
        data: {
          title: todo.title,
          content: todo.content ?? "",
          completed: todo?.completed ?? false,
          dueDate: todo?.dueDate,
          authorId: user.id,
          // Handle category relationships if provided
          categories: todo.categoryIds?.length ? {
            create: todo.categoryIds.map((categoryId) => ({
              category: { connect: { id: categoryId } }
            }))
          } : undefined,
        },
        include: {
          categories: {
            include: { category: true }
          }
        },
      });

      // Step 5: Transform data to match GraphQL schema
      const transformedTodo = {
        ...newTodo,
        categories: newTodo.categories.map((relation) =>
          withTypename(relation.category, "Category")
        ),
      };

      return withTypename(transformedTodo, "Todo");

    } catch (error) {
      // Step 6: Comprehensive error handling
      console.error("Error creating todo:", error);

      // Handle validation errors
      if (error instanceof ZodError) {
        return createValidationError(error);
      }

      // Handle database constraint violations
      if (error instanceof Prisma.PrismaClientKnownRequestError) {
        if (error.code === "P2002") {
          // Unique constraint violation
          return createConflictError(
            "A todo with this title already exists",
            "title"
          );
        }
        if (error.code === "P2003") {
          // Foreign key constraint violation
          return createNotFoundError("category", "Category");
        }
      }

      // Fallback to server error for unexpected issues
      return createServerError(
        "Failed to create todo",
        error instanceof Error ? error.message : String(error)
      );
    }
  },
};

This resolver implementation demonstrates several important patterns:

Early authentication checks: Fail fast if the user isn't authorized
Input validation: Use schema validation (Zod) to ensure data quality
Business logic validation: Check for conflicts and other business rules
Proper error categorization: Different types of failures return appropriate error types
Comprehensive error handling: Catch and categorize all possible error types
Rich error context: Include relevant information like field names and resource IDs

Step 5: Building Type-Safe Client-Side Error Handling

The real power of this approach becomes evident on the client side, where we can now handle errors in a completely type-safe manner. Let's walk through creating a comprehensive client-side error handling system.

Setting Up GraphQL Queries with Error Fragments

First, we need to set up our GraphQL queries to request all possible error types. We'll use fragments to keep our queries organized and reusable:

// Define reusable error fragments
export const ERROR_FRAGMENTS = gql`
  fragment ValidationErrorFragment on ValidationError {
    message
    code
    field
  }

  fragment NotFoundErrorFragment on NotFoundError {
    message
    code
    resourceId
    resourceType
  }

  fragment ConflictErrorFragment on ConflictError {
    message
    code
    conflictingField
  }

  fragment ServerErrorFragment on ServerError {
    message
    code
    details
  }

  fragment UnauthorizedErrorFragment on UnauthorizedError {
    message
    code
    operation
  }
`;

// Use fragments in mutations
const CREATE_TODO = gql`
  mutation CREATE_TODO($todo: TodoCreateInput!) {
    createTodo(todo: $todo) {
      ... on Todo {
        id
        title
        content
        completed
        dueDate
        createdAt
        updatedAt
        categories {
          id
          name
          color
        }
      }
      ...ValidationErrorFragment
      ...NotFoundErrorFragment
      ...ConflictErrorFragment
      ...ServerErrorFragment
      ...UnauthorizedErrorFragment
    }
  }
`;

Notice how we use inline fragments (... on Todo) for the success case and include all our error fragments. This ensures we get all the necessary data regardless of whether the operation succeeds or fails.

Creating Type-Safe Error Response Types

Next, we define TypeScript types that correspond to our GraphQL error types:

// Base error response type
type ErrorResponse = {
  __typename?: string;
  message?: string;
  code?: string;
  // Fields that might exist on specific error types
  field?: string | null;
  resourceId?: string;
  resourceType?: string;
  details?: string | null;
  conflictingField?: string | null;
  operation?: string;
};

// Specific typed interfaces for each error type
interface ValidationErrorResponse extends ErrorResponse {
  __typename: "ValidationError";
  field: string | null;
}

interface NotFoundErrorResponse extends ErrorResponse {
  __typename: "NotFoundError";
  resourceId: string;
  resourceType: string;
}

interface ServerErrorResponse extends ErrorResponse {
  __typename: "ServerError";
  details: string | null;
}

interface ConflictErrorResponse extends ErrorResponse {
  __typename: "ConflictError";
  conflictingField: string | null;
}

interface UnauthorizedErrorResponse extends ErrorResponse {
  __typename: "UnauthorizedError";
  operation: string;
}

// Enum for error types to enable exhaustive checking
export enum GraphQLErrorType {
  ValidationError = "ValidationError",
  NotFoundError = "NotFoundError", 
  ServerError = "ServerError",
  ConflictError = "ConflictError",
  UnauthorizedError = "UnauthorizedError",
}

These types enable TypeScript to provide compile-time checking and autocompletion when handling errors.

Building a Comprehensive Error Handling Utility

Now we can create a powerful, reusable error handling utility that leverages our typed error system:

// Configuration options for error handling
type ErrorHandlerOptions = {
  showToast?: boolean;           // Whether to show toast notifications
  logToConsole?: boolean;        // Whether to log errors to console
  onSuccess?: () => void;        // Callback for successful operations
  customMessages?: CustomMessagesMap;  // Custom error messages
};

// Type-safe custom messages map
type CustomMessagesMap = {
  [GraphQLErrorType.ValidationError]?: 
    | string 
    | ((error: ValidationErrorResponse) => string);
  [GraphQLErrorType.NotFoundError]?: 
    | string 
    | ((error: NotFoundErrorResponse) => string);
  [GraphQLErrorType.ServerError]?: 
    | string 
    | ((error: ServerErrorResponse) => string);
  [GraphQLErrorType.ConflictError]?: 
    | string 
    | ((error: ConflictErrorResponse) => string);
  [GraphQLErrorType.UnauthorizedError]?: 
    | string 
    | ((error: UnauthorizedErrorResponse) => string);
};

// Default error messages
const defaultErrorMessages: Record<string, string> = {
  [GraphQLErrorType.ValidationError]: "Please check your input and try again",
  [GraphQLErrorType.NotFoundError]: "The requested resource was not found",
  [GraphQLErrorType.ServerError]: "A server error occurred. Please try again later",
  [GraphQLErrorType.ConflictError]: "This action conflicts with existing data",
  [GraphQLErrorType.UnauthorizedError]: "You don't have permission to perform this action",
};

/**
 * Handles GraphQL mutation responses with comprehensive error handling
 */
export function handleGraphQLResponse<T extends ErrorResponse>(
  response: T | null | undefined,
  entityName: string,
  operation: string,
  options: ErrorHandlerOptions = {}
): boolean {
  const {
    showToast = true,
    logToConsole = true,
    onSuccess,
    customMessages = {},
  } = options;

  // Handle null/undefined responses
  if (!response) {
    if (showToast) {
      toast.error(`No response received for ${operation} ${entityName.toLowerCase()}`);
    }
    if (logToConsole) {
      console.error(`No response for ${operation} ${entityName}`);
    }
    return false;
  }

  // Check for success case
  if (response.__typename === entityName) {
    if (showToast) {
      toast.success(`${entityName} ${operation}d successfully!`);
    }
    if (onSuccess) {
      onSuccess();
    }
    return true;
  }

  // Handle error cases with type safety
  const errorType = response.__typename as GraphQLErrorType;

  if (errorType && Object.values(GraphQLErrorType).includes(errorType)) {
    let errorMessage: string;

    // Check for custom messages first
    if (errorType in customMessages) {
      const customMessage = customMessages[errorType];
      if (typeof customMessage === "function") {
        // Type-safe function calls based on error type
        switch (errorType) {
          case GraphQLErrorType.ValidationError:
            errorMessage = customMessage(response as ValidationErrorResponse);
            break;
          case GraphQLErrorType.NotFoundError:
            errorMessage = customMessage(response as NotFoundErrorResponse);
            break;
          case GraphQLErrorType.ServerError:
            errorMessage = customMessage(response as ServerErrorResponse);
            break;
          case GraphQLErrorType.ConflictError:
            errorMessage = customMessage(response as ConflictErrorResponse);
            break;
          case GraphQLErrorType.UnauthorizedError:
            errorMessage = customMessage(response as UnauthorizedErrorResponse);
            break;
          default:
            errorMessage = defaultErrorMessages[errorType] || "An error occurred";
        }
      } else {
        errorMessage = customMessage;
      }
    } else {
      errorMessage = defaultErrorMessages[errorType] || "An error occurred";
    }

    if (showToast) {
      toast.error(errorMessage);
    }

    if (logToConsole) {
      console.error(`Error ${operation}ing ${entityName}:`, {
        type: errorType,
        details: response,
      });
    }

    return false;
  }

  // Fallback for unexpected response structure
  if (showToast) {
    toast.error(`An unexpected error occurred while ${operation}ing the ${entityName.toLowerCase()}`);
  }
  if (logToConsole) {
    console.error(`Unexpected response structure:`, response);
  }

  return false;
}

This utility provides several key benefits:

Type safety: TypeScript ensures all error types are handled correctly
Flexibility: Supports custom error messages and callbacks
Consistency: Provides uniform error handling across the application
Rich context: Logs detailed error information for debugging
User experience: Shows appropriate toast notifications

Practical Usage in React Components

Finally, let's see how this all comes together in a real React component:

// TodoCreateForm.tsx
export function CreateTodoForm() {
  const form = useForm<TodoCreateFormData>({
    resolver: zodResolver(TodoCreateInputSchema),
    defaultValues: {
      title: "",
      content: "",
      completed: false,
      categoryIds: [],
    },
  });

  const [createTodo, { loading }] = useMutation(CREATE_TODO);

  const handleCreateTodo = async (data: TodoCreateFormData) => {
    try {
      const result = await createTodo({ 
        variables: { todo: data },
        // Optimistic updates and cache management
        refetchQueries: [{ query: GET_TODOS }],
      });

      // Use our type-safe error handler
      const success = handleGraphQLResponse(
        result.data?.createTodo, 
        "Todo", 
        "create", 
        {
          onSuccess: () => {
            form.reset();
            // Additional success handling like navigation
          },
          customMessages: {
            ConflictError: (error) => 
              `A todo with the title "${data.title}" already exists. Please choose a different title.`,
            ValidationError: (error) => 
              error.field 
                ? `Please check the ${error.field} field and try again.`
                : "Please check your input and try again.",
          },
        }
      );

      // You can also handle success/failure programmatically
      if (success) {
        // Perform additional success actions
        analytics.track('todo_created', { title: data.title });
      }

    } catch (error) {
      // Handle network errors or other unexpected issues
      console.error("Network error creating todo:", error);
      toast.error("Unable to connect to the server. Please check your connection.");
    }
  };

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(handleCreateTodo)} className="space-y-4">
        <FormField
          control={form.control}
          name="title"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Title</FormLabel>
              <FormControl>
                <Input placeholder="Enter todo title" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="content"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Description</FormLabel>
              <FormControl>
                <Textarea placeholder="Enter todo description" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <Button type="submit" disabled={loading}>
          {loading ? "Creating..." : "Create Todo"}
        </Button>
      </form>
    </Form>
  );
}

This component demonstrates several best practices:

Form validation: Client-side validation using Zod schema
Loading states: Proper loading indicators during mutations
Custom error messages: Context-specific error messages for better UX
Success handling: Actions to perform after successful operations
Network error handling: Separate handling for network vs. GraphQL errors
Analytics integration: Tracking successful operations
Cache management: Proper cache updates after mutations


This utility provides several key benefits:

1. **Type safety**: TypeScript ensures all error types are handled correctly
2. **Flexibility**: Supports custom error messages and callbacks
3. **Consistency**: Provides uniform error handling across the application
4. **Rich context**: Logs detailed error information for debugging
5. **User experience**: Shows appropriate toast notifications

Benefits of This Approach

Now that we've seen the complete implementation, let's examine the concrete benefits this approach provides over traditional GraphQL error handling patterns.

1. Complete Type Safety Throughout the Stack

The most significant advantage is end-to-end type safety. Unlike traditional approaches where errors are loosely typed or untyped:

Server-side benefits:

TypeScript enforces that all error creation follows the correct structure
Resolvers must handle all possible error scenarios explicitly
Code completion and IntelliSense work perfectly for error handling
Compile-time checks prevent common error handling mistakes

Client-side benefits:

GraphQL code generation creates precise TypeScript types for all error responses
Exhaustive checking ensures all error types are handled
IDE autocompletion shows exactly what fields are available on each error type
Impossible to access non-existent error fields or miss required handling

// TypeScript will enforce that you handle all union members
const handleResponse = (response: TodoResult) => {
  switch (response.__typename) {
    case "Todo":
      // Handle success
      break;
    case "ValidationError":
      // TypeScript knows this has 'field' property
      console.log(response.field);
      break;
    case "NotFoundError":
      // TypeScript knows this has 'resourceId' and 'resourceType'
      console.log(`${response.resourceType} ${response.resourceId} not found`);
      break;
    // TypeScript will error if you don't handle all cases
  }
};

2. Predictable and Consistent Error Structure

With traditional GraphQL error handling, clients never know what structure errors might have. Our approach provides:

Schema-driven predictability:

All possible error types are explicitly declared in the schema
Clients can discover error types through introspection
Error structure is self-documenting through GraphQL's type system
Breaking changes to error types are caught at compile time

Consistency across operations:

All mutations follow the same error handling pattern
Similar operations return similar error types
Error codes and structures are standardized across the API
No surprises or edge cases in error handling

3. Rich Contextual Error Information

Unlike generic error messages, our typed errors carry rich contextual information:

Validation errors include:

The specific field that failed validation
Structured error codes for programmatic handling
Clear, actionable error messages

Not found errors include:

The exact resource ID that wasn't found
The type of resource (Todo, Category, User, etc.)
Context for debugging and user feedback

Conflict errors include:

Which field caused the conflict
Specific information about the conflicting data
Guidance for resolving the conflict

This rich context enables:

Better user experiences: Specific, actionable error messages
Easier debugging: Complete context for investigating issues
Programmatic error handling: Clients can respond differently to different error types

4. Enhanced Developer Experience

The development experience improvements are substantial:

For API developers:

Clear patterns for handling all error scenarios
Utility functions ensure consistent error creation
Easy to add new error types without breaking existing code
Self-documenting error handling through types

For client developers:

Autocompletion for all error properties
Compile-time validation of error handling
Clear understanding of all possible error scenarios
Easy to write comprehensive error handling code

For QA and testing:

Predictable error structures enable comprehensive test coverage
Easy to test all error scenarios systematically
Type safety prevents runtime errors in test code
Error scenarios are explicit and discoverable

5. Superior Testability

Testing becomes much more straightforward and comprehensive:

// Server-side resolver tests
describe('createTodo', () => {
  it('should return ValidationError for invalid input', async () => {
    const result = await createTodo(invalidInput);
    expect(result.__typename).toBe('ValidationError');
    expect(result.field).toBe('title');
    expect(result.code).toBe('VALIDATION_ERROR');
  });

  it('should return ConflictError for duplicate titles', async () => {
    const result = await createTodo(duplicateInput);
    expect(result.__typename).toBe('ConflictError');
    expect(result.conflictingField).toBe('title');
  });
});

// Client-side error handling tests
describe('handleGraphQLResponse', () => {
  it('should show specific message for validation errors', () => {
    const validationError = {
      __typename: 'ValidationError',
      field: 'title',
      message: 'Title is required'
    };

    const result = handleGraphQLResponse(validationError, 'Todo', 'create');
    expect(result).toBe(false);
    expect(toast.error).toHaveBeenCalledWith('Please check the title field and try again.');
  });
});

6. Better Client-Side User Experience

The improved error handling directly translates to better user experiences:

Context-aware error messages:

"Please check the title field" instead of "Validation error"
"A todo with this title already exists" instead of "Conflict error"
"Category not found" instead of "Resource not found"

Appropriate error handling:

Form field highlighting for validation errors
Retry suggestions for server errors
Clear guidance for resolving conflicts
Proper error boundaries for different error types

Consistent error patterns:

All forms handle errors the same way
Users learn to expect consistent error feedback
Error states are predictable across the application

Implementation Considerations and Best Practices

While this approach provides significant benefits, there are important considerations and best practices to keep in mind when implementing it in your own projects.

GraphQL Schema Organization and Fragment Strategy

Organizing your error types and fragments properly is crucial for maintainability:

Centralized Error Type Definitions

Keep all error type definitions in a central schema file to ensure consistency:

# error.graphql
interface Error {
  message: String!
  code: String!
}

type ValidationError implements Error {
  message: String!
  code: String!
  field: String
}

type NotFoundError implements Error {
  message: String!
  code: String!
  resourceId: ID!
  resourceType: String!
}

# Add other error types...

Reusable Error Fragments

Create a comprehensive fragment library for error handling:

// errorFragments.ts
export const ERROR_FRAGMENTS = gql`
  fragment ValidationErrorFragment on ValidationError {
    message
    code
    field
  }

  fragment NotFoundErrorFragment on NotFoundError {
    message
    code
    resourceId
    resourceType
  }

  fragment ConflictErrorFragment on ConflictError {
    message
    code
    conflictingField
  }

  fragment ServerErrorFragment on ServerError {
    message
    code
    details
  }

  fragment UnauthorizedErrorFragment on UnauthorizedError {
    message
    code
    operation
  }
`;

// Base error fragment that includes all error types
export const ALL_ERRORS_FRAGMENT = gql`
  fragment AllErrorsFragment on Error {
    ...ValidationErrorFragment
    ...NotFoundErrorFragment
    ...ConflictErrorFragment
    ...ServerErrorFragment
    ...UnauthorizedErrorFragment
  }
`;

Domain-Specific Union Types

Create domain-specific union types for different areas of your application:

# User domain
union UserResult = User | ValidationError | NotFoundError | ConflictError | UnauthorizedError | ServerError
union UserDeleteResult = User | NotFoundError | UnauthorizedError | ServerError

# Todo domain  
union TodoResult = Todo | ValidationError | NotFoundError | ConflictError | UnauthorizedError | ServerError
union TodoDeleteResult = Todo | NotFoundError | UnauthorizedError | ServerError

# Category domain
union CategoryResult = Category | ValidationError | NotFoundError | ConflictError | UnauthorizedError | ServerError

Union Type Resolution Strategy

Proper union type resolution is critical for GraphQL to work correctly.
This way, GraphQL can resolve the correct type based on the __typename field.

// resolvers/index.ts
export const resolvers: Resolvers = {
  // Ensure proper __resolveType functions for all union types
  TodoResult: {
    __resolveType(obj) {
      if ("__typename" in obj && typeof obj.__typename === "string") {
        return obj.__typename;
      }
      throw new Error("Could not resolve type for TodoResult: __typename is missing");
    },
  },

  CategoryResult: {
    __resolveType(obj) {
      if ("__typename" in obj && typeof obj.__typename === "string") {
        return obj.__typename;
      }
      throw new Error("Could not resolve type for CategoryResult: __typename is missing");
    },
  },

  // Interface resolution for the base Error interface
  Error: {
    __resolveType(obj) {
      if ("__typename" in obj && typeof obj.__typename === "string") {
        return obj.__typename;
      }
      throw new Error("Could not resolve type for Error interface: __typename is missing");
    },
  },
};

Error Creation Utility Patterns

You can also create comprehensive utilities that ensure consistent error creation:

// utils/errors.ts

// Generic error creation with validation
export const createError = <T extends Record<string, any>>(
  typename: string,
  base: Pick<ErrorBase, 'message' | 'code'>,
  extra: T
): T & ErrorBase & { __typename: string } => ({
  ...base,
  ...extra,
  __typename: typename,
});

// Specific error creators with validation
export const createValidationError = (
  error: ZodError,
  customMessage?: string
): ValidationError => {
  const firstIssue = error.issues[0];
  return createError('ValidationError', {
    message: customMessage || 'Validation failed',
    code: 'VALIDATION_ERROR',
  }, {
    field: firstIssue?.path.join('.') || null,
  });
};

export const createNotFoundError = (
  resourceId: string,
  resourceType: string,
  customMessage?: string
): NotFoundError => createError('NotFoundError', {
  message: customMessage || `${resourceType} with id ${resourceId} not found`,
  code: 'NOT_FOUND',
}, {
  resourceId,
  resourceType,
});

// Utility to ensure __typename is added to success responses
export const withTypename = <T, K extends string>(
  obj: T,
  typename: K
): T & { __typename: K } => ({
  ...obj,
  __typename: typename,
});

// Result wrapper for consistent resolver returns
export const createSuccessResult = <T>(data: T, typename: string) => 
  withTypename(data, typename);

export const createErrorResult = (error: any) => error;

Database Integration Patterns

When integrating with databases, create patterns for handling common database errors:

// utils/databaseErrorHandling.ts
export const handleDatabaseError = (
  error: unknown,
  context: { resourceId?: string; resourceType?: string; operation?: string }
): GraphQLError => {
  if (error instanceof Prisma.PrismaClientKnownRequestError) {
    switch (error.code) {
      case 'P2002': // Unique constraint violation
        const field = error.meta?.target as string;
        return createConflictError(
          `A ${context.resourceType} with this ${field} already exists`,
          field
        );

      case 'P2025': // Record not found
        return createNotFoundError(
          context.resourceId || 'unknown',
          context.resourceType || 'Resource'
        );

      case 'P2003': // Foreign key constraint violation
        return createNotFoundError(
          'related resource',
          'Related Resource'
        );

      default:
        return createServerError(
          'Database operation failed',
          error.message
        );
    }
  }

  if (error instanceof ZodError) {
    return createValidationError(error);
  }

  return createServerError(
    `Failed to ${context.operation}`,
    error instanceof Error ? error.message : String(error)
  );
};

// Usage in resolvers
export const TodoMutations = {
  createTodo: async (_, { todo }, { prisma, user }) => {
    try {
      // ... business logic
    } catch (error) {
      return handleDatabaseError(error, {
        resourceType: 'Todo',
        operation: 'create todo'
      });
    }
  },
};

Performance Considerations

Query Complexity: Union types can increase query complexity. Use query complexity analysis to prevent abuse. I use Graphql Armor to limit query depth and complexity.
Fragment Usage: Encourage clients to use fragments to avoid requesting unnecessary error fields.
Caching: Union types work well with GraphQL caching strategies since each response has a clear type.

Conclusion

Typing errors as GraphQL types and using union responses provides a robust, type-safe approach to error handling in GraphQL APIs. This pattern offers significant benefits over traditional error handling approaches:

Predictable error structures that clients can rely on
Type safety throughout the entire stack
Rich error context for better user experiences
Improved testability and developer experience

While this approach requires more upfront design work, the long-term benefits in terms of maintainability, type safety, and developer experience make it a worthwhile investment for any serious GraphQL API.

The pattern scales well as your API grows, allowing you to add new error types and operations while maintaining consistency across your entire GraphQL schema. By embracing errors as first-class citizens in your GraphQL schema, you create a more robust and developer-friendly API.

Reference repo:

💻 If you want to see how I implemented this, please check this starter graphql template on my github

How to build a Fractional Star Rating Component with just React / Tailwindcss

Marcello Novelli — Mon, 10 Mar 2025 10:11:57 +0000

In this tutorial, we'll take star rating components to the next level by implementing fractional ratings. Unlike basic star ratings that only support whole numbers, our component will allow for quarter-star precision (0.25, 0.5, 0.75), providing a more nuanced rating experience.

This component uses only React and Tailwind CSS, making it easy to integrate into your web projects.

In a rush? Just check the 👉 full source code

Or check out the open-source UI library
👉 stackzero/commerce-ui

Why Fractional Star Ratings?

Fractional star ratings offer greater precision for review systems, especially in contexts where small differences matter:

E-commerce product reviews
Movie and book rating systems
Restaurant and service reviews
Performance evaluations

Key Features

Quarter-star Precision: Support for 0.25, 0.5, and 0.75 increments
SVG Gradients: Using SVG gradients to visually represent partial stars
Interactive Selection: Click position determines the fraction
Visual Feedback: Hover states show what rating will be selected
Fully Customizable: Adjustable colors, sizes, and number of stars

Step 1: Setting Up the Component Interface

First, let's define our component's props interface:

interface StarRatingBasicProps {
  value: number;              // Current rating value (can be fractional)
  onChange?: (value: number) => void;  // Callback when rating changes
  className?: string;         // Custom CSS classes
  iconSize?: number;          // Size of star icons
  maxStars?: number;          // Maximum number of stars
  readOnly?: boolean;         // Whether rating can be changed
  color?: string;             // Color of filled stars
}

Step 2: Creating a Unique ID Generator

We'll need unique IDs for our SVG gradients to ensure they don't interfere with each other when multiple rating components are used:

// Add ID generator outside component to maintain counter
let nextId = 0;
const generateStarIds = (count: number) =>
  Array.from({ length: count }, () => `star-${nextId++}`);

Step 3: Creating the Star Icon Component

Now we need to create the star icon component that will be reused for each star in the rating.
This component will handle click and hover interactions as well as the star's visual appearance.

Just like in the basic star rating component, we'll also add an inInteractive prop to determine if the star should respond to user interactions or not. This is useful when we want to set the component to read-only mode.

Let's create a memoized Star icon component for better performance:

const StarIcon = React.memo(
  ({
    iconSize,
    index,
    isInteractive,
    onClick,
    onMouseMove,
    style,
  }: {
    index: number;
    style: React.CSSProperties;
    iconSize: number;
    onClick: (e: React.MouseEvent<SVGElement>) => void;
    onMouseMove: (e: React.MouseEvent<SVGElement>) => void;
    isInteractive: boolean;
  }) => (
    <Star
      key={index}
      size={iconSize}
      fill={style.fill}
      color={style.color}
      onClick={onClick}
      onMouseMove={onMouseMove}
      className={cn(
        "transition-colors duration-200",
        isInteractive && "cursor-pointer"
      )}
      style={style}
    />
  )
);
StarIcon.displayName = "StarIcon";

👉 Notice how we're using onMouseMove instead of onMouseEnter. This is crucial for detecting the precise location within each star.

Step 4: Setting Up the Main Component

Let's initialize our component with its state and default props:

const StarRating_Fractions = ({
  className,
  color = "#e4c616",
  iconSize = 24,
  maxStars = 5,
  onChange,
  readOnly = false,
  value,
}: StarRatingBasicProps) => {
  const [hoverRating, setHoverRating] = React.useState<number | null>(null);
  // Generate stable IDs on component mount
  const [starIds] = React.useState(() => generateStarIds(maxStars));

I have added some defaults, but you can of course change them to your liking.

Step 5: Implementing the Fractional Rating Calculator

This is where the magic happens. We calculate the fraction based on where the user clicks within the star:

  const calculateRating = React.useCallback(
    (index: number, event: React.MouseEvent<SVGElement>) => {
      const star = event.currentTarget;
      const rect = star.getBoundingClientRect();
      const x = event.clientX - rect.left;
      const width = rect.width;
      const clickPosition = x / width;

      let fraction = 1;
      if (clickPosition <= 0.25) fraction = 0.25;
      else if (clickPosition <= 0.5) fraction = 0.5;
      else if (clickPosition <= 0.75) fraction = 0.75;

      return index + fraction;
    },
    []
  );

We're doing some geometry here:

Get the position of the click relative to the star element
Calculate the click position as a ratio of the star width. In this case, 0.25, 0.5, or 0.75 as we have four quarters.
Determine which quarter of the star was clicked
Return the base index plus the appropriate fraction

So for example, if the user clicks in the second quarter of the third star, the calculated rating would be 2.5. Thus, the star rating can now be fractional!

You could of course adjust the fraction granularity to your needs, such as thirds or tenths.

But I think quarters are a good balance between precision and usability.

Step 6: Implementing Interactive Handlers

Now we need to call the function calculateRating we just created whenever the user clicks on a star. This will calculate the new rating based on the click position.

So let's add the handlers for click and hover interactions:

  const handleStarClick = React.useCallback(
    (index: number, event: React.MouseEvent<SVGElement>) => {
      if (readOnly || !onChange) return;
      const newRating = calculateRating(index, event);
      onChange(newRating);
    },
    [readOnly, onChange, calculateRating]
  );

  const handleStarHover = React.useCallback(
    (index: number, event: React.MouseEvent<SVGElement>) => {
      if (!readOnly) {
        const previewRating = calculateRating(index, event);
        setHoverRating(previewRating);
      }
    },
    [readOnly, calculateRating]
  );

  const handleMouseLeave = React.useCallback(() => {
    if (!readOnly) {
      setHoverRating(null);
    }
  }, [readOnly]);

Step 7: Star Styling Logic

Unlike basic star ratings, fractional ratings require special styling with SVG gradients.

For example, if the rating is 3.75, the first three stars should be filled, and the fourth star should be 75% filled.

Based on this scenarios, there are essentially three types of "star styles" cases to consider:

When the rating is less than the current star index (difference ≤ 0) = Unfilled star
When the rating is greater than the current star index (difference ≥ 1) = Fully filled star
When the rating is between the current star index and the next (0 < difference < 1) = Partially filled star

Thus, we create a function to handle these 3 cases:

  const getStarStyle = React.useCallback(
    (index: number) => {
      const ratingToUse =
        !readOnly && hoverRating !== null ? hoverRating : value;
      const difference = ratingToUse - index;

      if (difference <= 0) return { color: "gray", fill: "transparent" };
      if (difference >= 1) return { color: color, fill: color };

      return {
        color: color,
        fill: `url(#${starIds[index]})`,
      } as React.CSSProperties;
    },
    [readOnly, hoverRating, value, color, starIds]
  );

This function determines how each individual star should be styled:

Unfilled stars (difference ≤ 0): gray outline, transparent fill
Fully filled stars (difference ≥ 1): colored outline and fill
Partially filled stars (0 < difference < 1): uses SVG gradient

The first two cases are straightforward, but the third case requires a bit more work. We use an SVG gradient to fill the star with the appropriate percentage of color.
Thus, for the third case, we return an object with the fill property set to a linear gradient URL.

The # symbol in url(#${starIds[index]}) indicates a reference to an element with that ID within the same document, connecting the star to its specific gradient. This is how we link the star to its partial fill gradient (more on this below).

This is just an example, you can customize the styling to fit your design. For example, you could use different colors for the outline and fill, or even add animations.

Step 8: Creating SVG Gradient Definitions

To render partial stars, we need to create SVG gradient definitions.

We will later insert this gradient definition into the DOM using an invisible SVG element with <defs>.

  const renderGradientDefs = () => {
    const ratingToUse = !readOnly && hoverRating !== null ? hoverRating : value;
    const partialStarIndex = Math.floor(ratingToUse);
    const partialFill = (ratingToUse % 1) * 100;

    // Only create gradient for partial star
    if (partialFill > 0) {
      return (
        <linearGradient
          id={starIds[partialStarIndex]}
          x1="0%"
          y1="0%"
          x2="100%"
          y2="0%"
        >
          <stop offset={`${partialFill}%`} stopColor={color} />
          <stop offset={`${partialFill}%`} stopColor="transparent" />
        </linearGradient>
      );
    }
    return null;
  };

This creates a linear gradient that fills exactly the percentage of the star that should be colored.

Step 9: Generating the Stars

Now, let's create the array of star components:

  const renderStars = () => {
    return Array.from({ length: maxStars }).map((_, index) => {
      const style = getStarStyle(index);
      return (
        <StarIcon
          key={starIds[index]}
          index={index}
          style={style}
          iconSize={iconSize}
          onClick={(e) => handleStarClick(index, e)}
          onMouseMove={(e) => handleStarHover(index, e)}
          isInteractive={!readOnly}
        />
      );
    });
  };

This just maps over the number of stars and generates the star components with the appropriate style and interaction handlers.

Step 10: Final Component Assembly

Finally, let's put it all together in the return statement:

  return (
    <div
      className={cn("relative flex items-center gap-x-0.5", className)}
      onMouseLeave={handleMouseLeave}
    >
      <svg width="0" height="0" style={{ position: "absolute" }}>
        <defs>{renderGradientDefs()}</defs>
      </svg>
      {renderStars()}
    </div>
  );
};

Notice how we include an invisible SVG with our gradient definitions, followed by the rendered stars.

This essentially inserts the gradient definitions into the DOM without affecting the visual layout while allowing the stars to reference them (Remeber the url(#${starIds[index]}) in the getStarStyle function).

Usage Examples

// Interactive fractional rating
<StarRating_Fractions
  value={3.75}
  onChange={(newValue) => console.log(`New rating: ${newValue}`)} 
/>

// Read-only fractional rating with custom color
<StarRating_Fractions
  value={4.25}
  readOnly={true}
  color="#ff6b00"
  iconSize={32}
/>

Technical Challenges and Solutions

Challenge 1: Accurate Fractional Selection

The component needs to detect where within the star the user clicked to determine the fraction.

Solution: We use getBoundingClientRect() and calculate click position as a ratio of the star's width.

Challenge 2: Visually Representing Partial Stars

We need a way to fill only part of a star.

Solution: SVG gradients! We create a linear gradient that fills exactly the right percentage of the star.

Challenge 3: Linking Stars to Gradients

Each star needs to reference its unique gradient.

Solution: We insert into the DOM an invisible SVG element with <defs> containing the gradient definitions. We then link each star to its corresponding gradient using a unique ID and the url(#id) syntax.

Challenge 4: Handling Multiple Instances

Multiple rating components on the same page would have conflicting gradient IDs.

Solution: We generate unique IDs for each star's gradient using a counter.

Accessibility Considerations

Use semantic markup and ARIA attributes for better screen reader support
Ensure keyboard navigability for users who can't use a mouse
Provide sufficient color contrast for visibility

Possible Enhancements

Supporting different fractions (thirds, tenths, etc.)
Adding animation effects during rating changes
Implementing half-star ratings for simpler use cases
Adding tooltips to display the exact numerical rating

Conclusion

Fractional star ratings add a level of precision and polish to your user interface that whole-star ratings cannot match. While they require more complex implementation with SVG gradients and click position detection, the enhanced user experience is worth the effort.

With this component, you can offer your users a more refined and expressive way to provide ratings and feedback.

Full Source Code + More Examples

Here you can get the full source code with more examples!

Or check out the open-source UI library
👉 stackzero/commerce-ui

How to build a Star Rating component with Tailwindcss ⭐

Marcello Novelli — Mon, 10 Feb 2025 21:12:23 +0000

In this tutorial, we'll build a reusable Star Rating component using React. This component will support both interactive and read-only modes, custom colors, and hover effects.

This is the kind of component that you often see in e-commerce sites or review apps.

In a rush? Just check the 👉 full source code

Key features and requirements

Interactivity: The component switches between interactive and read-only modes based on the readOnly prop.
Hover Effects: In interactive mode, hovering over stars shows a preview of the rating.
Customization: Supports custom colors, sizes, and number of stars.
Performance: Uses React.memo and useMemo to optimize rendering performance.
Accessibility: Includes proper cursor styles and visual feedback for interactive elements.

Step 1: Setting Up the Component Interface

First, let's define the props interface for our component. This will help us understand what customization options our component will support.

interface StarRatingBasicProps {
  value: number;              // Current rating value
  onChange?: (value: number) => void;  // Callback when rating changes
  className?: string;         // Custom CSS classes
  iconSize?: number;          // Size of star icons
  maxStars?: number;         // Maximum number of stars
  readOnly?: boolean;        // Whether rating can be changed
  color?: string;           // Color of filled stars
}

Step 2: Creating the Star Icon Component

Let's create a memoized Star icon component that will be reused for each star in the rating. This helps with performance optimization.

const StarIcon = React.memo(({
  iconSize,
  index,
  isInteractive,
  onClick,
  onMouseEnter,
  style,
}: {
  index: number;
  style: React.CSSProperties;
  iconSize: number;
  onClick: () => void;
  onMouseEnter: () => void;
  isInteractive: boolean;
}) => (
  <Star
    key={index}
    size={iconSize}
    fill={style.fill}
    color={style.color}
    onClick={onClick}
    onMouseEnter={onMouseEnter}
    className={cn(
      "transition-colors duration-200",
      isInteractive && "cursor-pointer hover:scale-110"
    )}
    style={style}
  />
));

Step 3: Setting Up the Main Component State

Now, let's set up the main component with its state and default props:

const StarRating_Basic = ({
  className,
  color = "#FFD700",      // Default gold color
  iconSize = 24,          // Default size
  maxStars = 5,          // Default max stars
  onChange,
  readOnly = false,
  value,
}: StarRatingBasicProps) => {
  const [hoverRating, setHoverRating] = React.useState<number | null>(null);

I have added some defaults, but you can of course change them to your liking.

Step 4: Implementing Interactive Handlers

Let's add the handlers for click and hover interactions. These will be needed to create a nice hover effect, in a way creating a sort of rating "preview", before the new rating is clicked.

Since we just want to preview a rating on hover, when the mouse leaves the component, we want to display the original rating. Thus we implement a handleMouseLeave handler to reset the hoverRating to null.

The handlers must also check for the readOnly condition to avoid updating the rating when not needed.

  const handleStarClick = React.useCallback(
    (index: number) => {
      if (readOnly || !onChange) return;
      const newRating = index + 1;
      onChange(newRating);
    },
    [readOnly, onChange]
  );

  const handleStarHover = React.useCallback(
    (index: number) => {
      if (!readOnly) {
        setHoverRating(index + 1);
      }
    },
    [readOnly]
  );

  const handleMouseLeave = React.useCallback(() => {
    if (!readOnly) {
      setHoverRating(null);
    }
  }, [readOnly]);

Step 5: Star Styling Logic

Add the logic to determine each star's appearance:

  const getStarStyle = React.useCallback(
    (index: number) => {
      const ratingToUse =
        !readOnly && hoverRating !== null ? hoverRating : value;
      return {
        color: ratingToUse > index ? color : "gray",
        fill: ratingToUse > index ? color : "transparent",
      } as React.CSSProperties;
    },
    [readOnly, hoverRating, value, color]
  );

We assign a const ratingToUse and then we use such a variable to determine which color / fill a "star" should have.

Step 6: Generating the Stars

Then, all we need to do is display the star icons as a dynamic array whose length is determined by the maxStars prop.

So we create the array of star components using the styling and interaction handlers:

  const stars = React.useMemo(() => {
    return Array.from({ length: maxStars }).map((_, index) => {
      const style = getStarStyle(index);
      return (
        <StarIcon
          key={index}
          index={index}
          style={style}
          iconSize={iconSize}
          onClick={() => handleStarClick(index)}
          onMouseEnter={() => handleStarHover(index)}
          isInteractive={!readOnly}
        />
      );
    });
  }, [maxStars, getStarStyle, iconSize, handleStarClick, handleStarHover, readOnly]);

Step 7: Final Component Assembly

Finally, let's put it all together in the return statement:

  return (
    <div
      className={cn("flex items-center gap-x-0.5", className)}
      onMouseLeave={handleMouseLeave}
    >
      {stars}
    </div>
  );

Usage Example

// Interactive rating
<StarRating_Basic
  value={3}
  onChange={(newValue) => console.log(`New rating: ${newValue}`)} />
// Read-only rating with custom color
<StarRating_Basic
  value={4.5}
  readOnly={true}
  color="#FF0000"
  iconSize={32}
/>

Full Source Code + Examples

Here you can get the full source code with examples!