Dropul

A lightweight, hover-triggered inline dropdown component for React. Display text, images, profiles, commit grids, or real GitHub contribution data on hover — with smooth CSS animations and dark mode support.

Installation

npm install dropul

No additional dependencies required! Dropul uses pure CSS animations.

Setup

Option 1: Import the CSS (Recommended)

Simply import the included stylesheet in your app's entry point:

// In your _app.tsx, layout.tsx, or main entry file
import 'dropul/styles.css';

That's it! All styles are included.

Option 2: Tailwind CSS Configuration

If you prefer to use Tailwind and want to customize styles, add the package to your Tailwind config:

// tailwind.config.js or tailwind.config.ts
module.exports = {
  content: [
    // ... your other content paths
    './node_modules/dropul/**/*.{js,mjs}',
  ],
  // ...
}

Dark Mode

Dropul fully supports Tailwind's dark mode. Just ensure your Tailwind config has dark mode enabled:

// tailwind.config.js
module.exports = {
  darkMode: 'class', // or 'media'
  // ...
}

The component will automatically adapt to light/dark themes.

Usage

Import and use anywhere in your app:

import { Dropout } from 'dropul';

function App() {
  return (
    <p>
      Check out <Dropout variant="text" trigger="this feature" text="A simple tooltip!" /> in action.
    </p>
  );
}

Variants

Text

<Dropout 
  variant="text" 
  trigger="hover me" 
  text="This is a tooltip message." 
/>

Image

<Dropout 
  variant="image" 
  trigger="preview" 
  imageSrc="/path/to/image.jpg" 
  imageAlt="Description" 
  size="default" // or "sm" for smaller images
/>

Image + Text

<Dropout 
  variant="image-text" 
  trigger="Jane Doe" 
  imageSrc="/avatar.jpg" 
  title="Jane Doe" 
  subtitle="Software Engineer" 
/>

GitHub Contributions

Display real GitHub contribution data for any user:

<Dropout 
  variant="github-contributions" 
  trigger="my commits" 
  username="octocat"
  apiEndpoint="/api/github-contributions" // See below
/>

API Route Setup (Required for CORS)

Due to browser CORS restrictions, you need to create a server-side API route to fetch GitHub data.

Option 1: One-line export (Recommended)

// app/api/github-contributions/route.ts
export { GET } from 'dropul/github';

That's it! The package includes a pre-built handler.

Option 2: Custom handler with helper function

// app/api/github-contributions/route.ts
import { fetchGitHubContributions } from 'dropul/github';
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const username = request.nextUrl.searchParams.get('username');
  if (!username) {
    return NextResponse.json({ error: 'Username required' }, { status: 400 });
  }
  
  const contributions = await fetchGitHubContributions(username, 12);
  return NextResponse.json(contributions);
}

Commit Grid (Custom Data)

Display a custom commit-style grid with your own data:

<Dropout 
  variant="commit-grid" 
  trigger="activity" 
  data={[0, 1, 2, 3, 4, 2, 1, 0, 3, 4, 2, 1, 0, 1]} // values 0-4
  columns={7}
/>

Props

| Prop | Type | Description | |------|------|-------------| | trigger | ReactNode | The content that triggers the dropdown on hover | | variant | 'text' \| 'image' \| 'image-text' \| 'commit-grid' \| 'github-contributions' | The type of content to display | | href | string? | Optional link URL - makes trigger an anchor tag | | triggerClassName | string? | Custom classes for the trigger element | | ariaLabel | string? | Accessibility label (default: "Dropdown") |

Variant-specific props

text

• text (string) — The tooltip text to display

image

• imageSrc (string) — Image URL
• imageAlt (string?) — Alt text for the image
• size ('sm' | 'default'?) — Image size (default: 'default')

image-text

• imageSrc (string) — Image URL
• title (string) — Title text
• subtitle (string?) — Subtitle text
• imageAlt (string?) — Alt text for the image

commit-grid

• data (number[]) — Array of values 0-4 representing intensity
• columns (number?) — Grid columns (default: 7)

github-contributions

• username (string) — GitHub username
• apiEndpoint (string?) — API route URL for fetching contributions

Features

• 🎨 Dark mode support — Automatically adapts to light/dark themes
• ⚡ Zero animation dependencies — Uses pure CSS animations with spring effect
• 📱 Mobile friendly — Works with touch events
• ♿ Accessible — Keyboard navigation and ARIA attributes
• 🖼️ Image preloading — Images are preloaded on hover for instant display
• 🎯 Lightweight — No Framer Motion or other animation libraries required

Requirements

• React 18+ or 19
• Tailwind CSS (with dropul added to content config)

License

MIT