react-starmap

react-starmap

A React component library for rendering interactive galactic constellation visualizations with pan, zoom, and time-based filtering capabilities.

Features

• 🌌 N-gon Constellation Rendering - Automatically renders constellations as N-sided polygons based on star count
• 🖱️ Pan & Zoom - Click and drag to pan, scroll wheel to zoom with configurable limits
• ⏰ Time Scrubber - Filter constellations by anniversary date with dual-range slider
• ✨ Smooth Animations - Fade in/out effects when constellations appear or disappear
• 📊 Strongly Typed - Full TypeScript support with comprehensive type definitions
• 🎨 Customizable - Configure dimensions, zoom limits, and optional time filtering

Installation

npm install react-starmap

Usage

Basic Example

import { Starmap, Galaxy } from 'react-starmap';

const galaxy: Galaxy = {
  constellations: [
    {
      label: "Orion",
      stars: 7,
      anniversary: new Date("2023-01-15"),
    },
    {
      label: "Big Dipper",
      stars: 7,
      anniversary: new Date("2023-06-20"),
    },
    {
      stars: 5, // Label is optional
      anniversary: new Date("2024-03-10"),
    },
  ],
};

function App() {
  return (
    <Starmap
      galaxy={galaxy}
      width={800}
      height={600}
      enableTimeScrubber={true}
    />
  );
}

With Time Scrubber Control

import { Starmap, Galaxy } from 'react-starmap';
import { useState } from 'react';

function App() {
  const [enableTimeScrubber, setEnableTimeScrubber] = useState(false);

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={enableTimeScrubber}
          onChange={(e) => setEnableTimeScrubber(e.target.checked)}
        />
        Enable Time Scrubber
      </label>

      <Starmap
        galaxy={galaxy}
        width={1000}
        height={700}
        enableTimeScrubber={enableTimeScrubber}
        minZoom={0.5}
        maxZoom={3}
      />
    </div>
  );
}

API Reference

Starmap Component Props

Prop	Type	Default	Description
galaxy	Galaxy	required	Galaxy data containing constellations
width	number	800	Width of the starmap canvas in pixels
height	number	600	Height of the starmap canvas in pixels
enableTimeScrubber	boolean	false	Enable time-based filtering with date range slider
minZoom	number	0.5	Minimum zoom level
maxZoom	number	3	Maximum zoom level

Data Types

Galaxy

interface Galaxy {
  constellations: Constellation[];
}

Constellation

interface Constellation {
  label?: string;      // Optional text label displayed under constellation
  stars: number;       // Number of stars (determines N-gon shape)
  anniversary: Date;   // Date for time-based filtering
}

Interactive Controls

• Pan: Click and drag anywhere on the canvas to pan around the galaxy
• Zoom: Use mouse scroll wheel to zoom in/out (respects min/max zoom limits)
• Time Filter: When enabled, use the dual-range sliders to filter constellations by anniversary date
• Reset Time: Click the "Reset" button to show all constellations (sets to "All Time" mode)

Time Scrubber

The time scrubber feature allows filtering constellations based on their anniversary dates:

• Enable via the enableTimeScrubber prop
• Two range sliders appear at the bottom of the canvas
• Adjust the sliders to set minimum and maximum date range
• Only constellations with anniversaries in the selected range are displayed
• Constellations fade in/out smoothly when the filter changes
• Click "Reset" to return to showing all constellations

Animation Details

• Initial Load: All constellations fade in over 0.5s when first rendered
• Time Filter Changes: Constellations smoothly fade out when filtered, fade in when included
• Smooth Transitions: All animations use ease-in-out timing for natural feel

Constellation Rendering

Each constellation is rendered as:

• An N-sided polygon (N = number of stars)
• Stars positioned at each vertex of the polygon
• Optional label text displayed below the constellation
• Size scales with star count (more stars = larger constellation)
• Polygon filled with semi-transparent indigo, outlined in lighter indigo
• Stars rendered as golden circles with light glow effect

License

MIT