@react-photo-gallery/ui

A Tailwind + shadcn/ui powered component library exposing a responsive PhotoGallery alongside foundational UI primitives (Button, Card, cn helper, etc.).

Installation

pnpm add @react-photo-gallery/ui

Setup

1. Install Dependencies

npm install @oikihome/react-photo-gallery
# or
pnpm add @oikihome/react-photo-gallery
# or
yarn add @oikihome/react-photo-gallery

2. Tailwind Configuration

Add the package to your Tailwind content globs so class names authored inside the library are preserved during tree-shaking (ensure tailwindcss and tailwindcss-animate are installed in your app):

// tailwind.config.ts
export default {
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@oikihome/react-photo-gallery/dist/**/*.{js,jsx}"
  ],
  plugins: [require("tailwindcss-animate")],
};

3. CSS Setup

Option A: Import the provided CSS file (Recommended)

// In your main CSS file or index.tsx
import '@oikihome/react-photo-gallery/styles.css';

Option B: Copy CSS custom properties to your CSS

Copy the CSS custom properties from the package's styles.css file to your main CSS file:

/* Add these CSS custom properties to your main CSS file */
:root {
  --background: 0 0% 100%;
  --foreground: 224 71.4% 4.1%;
  --card: 0 0% 100%;
  --card-foreground: 224 71.4% 4.1%;
  --popover: 0 0% 100%;
  --popover-foreground: 224 71.4% 4.1%;
  --primary: 220.9 39.3% 11%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.75rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 41% 9.2%;
  --card-foreground: 210 40% 98%;
  --popover: 222.2 41% 9.2%;
  --popover-foreground: 210 40% 98%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 217.2 32.6% 17.5%;
  --secondary-foreground: 210 40% 96.1%;
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  --accent: 217.2 32.6% 17.5%;
  --accent-foreground: 210 40% 98%;
  --destructive: 0 62.8% 49.6%;
  --destructive-foreground: 210 40% 98%;
  --border: 217.2 32.6% 17.5%;
  --input: 217.2 32.6% 17.5%;
  --ring: 224.3 76.3% 48%;
  --radius: 0.75rem;
}

4. Troubleshooting Overlay Issues

If the photo gallery overlay (Showcase component) is not appearing properly or is not overlapping correctly with your UI:

1. Ensure CSS is imported: Make sure you've imported the CSS file as described in step 3
2. Check z-index conflicts: The overlay uses z-index: 999999. If you have elements with higher z-index values, they may appear above the overlay
3. Verify Tailwind configuration: Ensure your Tailwind config includes the package's content paths
4. Check for CSS resets: Some CSS resets might interfere with the component's positioning

Usage

import { Button, Card, CardContent, CardHeader, CardTitle, PhotoGallery } from "@oikihome/react-photo-gallery";

export function DemoGallery() {
  const photos = [
    { id: "sunset", src: "https://example.com/sunset.jpg", alt: "Sunset" },
    { id: "forest", src: "https://example.com/forest.jpg", alt: "Forest" },
  ];

  return (
    <Card>
      <CardHeader>
        <CardTitle>Latest Shots</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <PhotoGallery photos={photos} columns={2} gap={16} />
        <Button variant="secondary">View all</Button>
      </CardContent>
    </Card>
  );
}

Development scripts

pnpm turbo run dev --filter=@react-photo-gallery/ui   # tsup in watch mode
pnpm turbo run build --filter=@react-photo-gallery/ui # produce dist/ outputs
pnpm lint --filter=@react-photo-gallery/ui            # Biome checks
pnpm format --filter=@react-photo-gallery/ui          # Biome formatting

Tsup emits CommonJS, ESM, and type declarations to dist/, ready for publication.