DOCSEARCHbyAlgolia
Submit Docs

StackZero UI

repository·main·Indexed 42 days ago

https://github.com/stackzero-labs/ui

A high-quality e-commerce component library built with React, Next.js, Tailwind CSS v4, and shadcn/ui. It provides a tiered system of low-level components, complex blocks, and complete pages designed to be copy-pasted or installed via CLI into online store projects.

Tokens
18.1K
Snippets
68
Records
95
Agent score
54%

What's inside StackZero UI

  1. Overview of stackzero/commerce-ui

    main

    stackzero/commerce-ui is a collection of UI primitives designed for building e-commerce sites and commerce applications. It is optimized for the following tech stack:

    • React
    • Next.js
    • Tailwind CSS (specifically v4)
    • shadcn/ui

    The library is organized into three hierarchical levels of abstraction:

    1. Components: Low-level UI primitives.
    2. Blocks: Complex layouts and sections built by composing components.
    3. Pages: Complete page structures built by composing blocks and components.

    All assets are designed to be copy-pasted directly into your project, giving you full control over the code.

  2. Overview of the Xeon Landing Page Template

    main
    Xeon is a pre-built landing page template designed for SaaS, startups, and product showcases. It is intended to save significant development time by providing a professional, responsive, and SEO-optimized foundation. The template includes pre-designed sections such as Hero, Features, Pricing, FAQ, and Contact.

  3. Implementing partial star fills with SVG Gradients

    main

    Fractional stars are rendered using SVG <linearGradient> definitions.

    To achieve this:

    1. Generate Unique IDs: Use a unique ID generator for each star to ensure gradients don't conflict when multiple components exist on one page.
    2. Create Gradient Definitions: An invisible <svg> containing <defs> is rendered. It calculates the partialFill percentage using (ratingToUse % 1) * 100 and creates a gradient with two <stop> elements: one for the color at the partialFill offset, and one for transparent at the same offset.
    3. Apply Fill: The star icon's fill property is set to url(#${starId}), linking it to the specific gradient definition.
    // Example of the gradient definition logic
const renderGradientDefs = () => {
  const ratingToUse = !readOnly && hoverRating !== null ? hoverRating : value;
  const partialStarIndex = Math.floor(ratingToUse);
  const partialFill = (ratingToUse % 1) * 100;

  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;
};

  4. Understand the stackzero/commerce-ui architecture

    main

    The library is organized into two primary levels of UI abstraction:

    1. Components: Small, self-contained, and flexible UI pieces designed to be used independently or as building blocks for larger structures.
    2. Blocks: Larger, context-specific UI sections (e.g., product pages or checkout flows) typically composed of multiple components.

    You can use components to build custom blocks or use the provided blocks to assemble entire pages.

  5. Xeon Technical Stack and Features

    main

    The Xeon template is built using a modern web development stack to ensure high performance and ease of customization:

    • Framework: Next.js 15 (App Router) and React 19.
    • Styling: Tailwind CSS v4 and PostCSS.
    • Language: TypeScript with strict linting.
    • Design: Dark theme compatible, fully responsive, and component-based architecture.
    • Assets: Includes SVG and image assets.

  6. Accessibility best practices for star rating components

    main

    When implementing star rating components, ensure the following for a high-quality user experience:

    • Semantic Markup: Use appropriate HTML elements and ARIA attributes to ensure screen readers can interpret the rating state.
    • Keyboard Navigability: Ensure users can interact with and change ratings using only a keyboard.
    • Color Contrast: Maintain sufficient color contrast between the stars and the background to ensure visibility for all users.

  7. How fractional rating calculation works

    main

    To support quarter-star precision, the component calculates the rating based on the horizontal click position relative to the star's width.

    1. It retrieves the bounding rectangle of the star element.
    2. It calculates the clickPosition as a ratio: x / width.
    3. It maps the ratio to a fraction:
      • ≤ 0.25 $\rightarrow$ 0.25
      • ≤ 0.50 $\rightarrow$ 0.5
      • ≤ 0.75 $\rightarrow$ 0.75
      • Otherwise $\rightarrow$ 1 (full star).
    4. The final rating is the index of the star plus the calculated fraction.
    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;
  },
  []
);

  9. Use the MCP server to generate components with AI

    main

    Once the MCP server is installed and configured, your AI agent (in Cursor, Windsurf, or Claude) can access the context of stackzero-labs components and blocks. You can use natural language prompts to build commerce applications.

    Example prompts:

    • "Create a product page using star rating fractional component"
    • "Create a banner component similar to stackzero's banner-01."

  10. Access the full source code for the Animated Upvote Rating Component

    main

    The complete implementation and additional usage examples for the Animated Upvote Rating Component can be found in the official component documentation. This includes the full source code and various implementation patterns for integrating the component into your React application.

    [Full Source Code and Examples](/docs/components/upvote-rating/animated)

  11. Install the Image Carousel component

    main

    To use the Image Carousel component, you must first install its peer dependencies and then copy the component source into your project.

    1. Install dependencies

    Install the following packages using your preferred package manager:

    • @radix-ui/react-dialog
    • embla-carousel
    • embla-carousel-react
    • react-zoom-pan-pinch
    npm install @radix-ui/react-dialog embla-carousel embla-carousel-react react-zoom-pan-pinch

  12. Customize the Star Rating component

    main

    The Star Rating component supports customization of the maximum number of stars displayed and the color of the icons.

    Change max rating

    To change how many stars are displayed in the component, adjust the maximum rating property (refer to the component's API for the specific prop name, typically max or count).

    Custom icons color

    You can apply custom colors to the star icons to match your application's theme.