🌌 space-background

🚀 A lightweight, stunning, and animated space-themed React background with stars, planets, and meteors. Perfect for modern UIs, portfolios, and landing pages.

A beautiful, animated space-themed background component for React with configurable stars, planets, meteors, parallax motion, and theme toggling between light, dark, and dark-static.

🌠 Perfect for modern, aesthetic portfolios, landing pages, or immersive UIs.

📚 Table of Contents

• ✨ Features
• 🎥 Preview
• 📦 Installation
• 🚀 Quick Start
• 🌗 Theme Modes
• 🧩 Components
• 🧾 Props Reference
• 🛠 Requirements
• 🧭 Use Cases
• 📄 License
• 🤝 Contributing
• 🧑‍💻 Local Dev Setup
• 🌍 Used In

---

✨ Features

• ⚙️ Fully customizable starfields, meteors, and planet orbits
• 🌗 Built-in theme toggle: light / dark / dark-static
• 🎨 Framer Motion animation with parallax support
• ⚡ Lightweight and tree-shakable
• 🧠 TypeScript types included
• 📦 Works with React 18+ and Vite
• <SpaceBackground /> is a lightweight drop-in animated canvas.
• <Space /> is a developer-focused scene component with live control panels, ideal for prototyping or fine-tuning visual settings.

---

🎥 Preview

🌌 Animated Demo

👆 A glimpse of stars, planets, meteors, and theme/hue toggling in motion.

🖼 Static Screenshots

   

✅ Static views showing different modes and control panels.

---

📦 Installation

npm install space-background
# or
yarn add space-background
# or
pnpm add space-background

💡 Don’t forget to import "space-background/style.css" in your main.jsx and ensure Tailwind CSS is installed for styles to work properly.

---

🚀 Quick Start

• In App.jsx (JavaScript)

import SpaceBackground, {
  ThemeToggle,
  useThemeAnimationToggle,
} from "space-background";

function App() {
  const disableAnimation = useThemeAnimationToggle();

  return (
    <>
      <ThemeToggle />
      <SpaceBackground visual={{ disableAnimation: disableAnimation }} />
    </>
  );
}

export default App;

• In App.tsx (TypeScript)

import SpaceBackground, {
  ThemeToggle,
  useThemeAnimationToggle,
} from "space-background";

function App() {
  const disableAnimation = useThemeAnimationToggle();
  return (
    <>
      <ThemeToggle />
      <SpaceBackground visual={{ disableAnimation: disableAnimation }} />
    </>
  );
}

export default App;

✅ TypeScript support is built-in. All props are typed, including stars, planets, meteors, and visual.

• Import Styles in main.jsx / main.tsx

// main.jsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.jsx";
import "./index.css";
import "space-background/style.css"; // Add this line in main.jsx

createRoot(document.getElementById("root")).render(
  <StrictMode>
    <App />
  </StrictMode>
);

// main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "space-background/style.css"; // Add this line in main.tsx
import App from "./App.tsx";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

💡 This CSS import is essential for background and animation styles. Ensure Tailwind is working correctly.

• 💡 Tailwind CSS must be installed for styles to work correctly.

---

🌗 Theme Modes

Mode	Animation	Class Applied	Icon
light	❌	none	🌙
dark	✅	dark	☀️
dark-static	❌	dark	⭐

🔁 ThemeToggle cycles modes: light → dark → dark-static → light

💾 Persists user preference using localStorage

📣 Dispatches a theme-mode-change event with the current mode in event.detail

---

🧩 Components

• SpaceBackground

  The main animated space-themed background component.
  Highly customizable with props for stars, clusters, planets, meteors, and visual settings.

  Minimal usage:

  <SpaceBackground />

  Full props example:

  <SpaceBackground
    stars={{ count: 150, ... }}
    clusters={{ count: 3, ... }}
    planets={{ size: 1.6, ... }}
    meteors={{ enable: true, ... }}
    visual={{ disableAnimation: false, ... }}
  />

  • You can hide the hue control panel by setting visual={{ showHueControl: false }}.

  <SpaceBackground
    visual={{
      showHueControl: false, // hides hue picker
    }}
  />

• Space

  An advanced animated space scene component with developer controls — ideal for demos, testing, and interactive UIs.

  Press Ctrl + Shift + H to toggle the live dev control panel.

  Has the same props as SpaceBackground, plus an interactive editing UI.

  Minimal usage:

  <Space />

  Full props example:

  <Space
    stars={{ count: 150, ... }}
    clusters={{ count: 3, ... }}
    planets={{ size: 1.6, ... }}
    meteors={{ enable: true, ... }}
    visual={{ disableAnimation: false, ... }}
  />

  • You can hide the hue control panel by setting visual={{ showHueControl: false }}.

  <Space
    visual={{
      showHueControl: false, // hides hue picker
    }}
  />

• ThemeToggle

  A minimal, responsive button that toggles the theme between light, dark, and dark-static.

  ✅ Features:

  • Cycles through all three modes: light → dark → dark-static
  • Automatically applies dark class to <html>
  • Persists user preference using localStorage
  • Dispatches theme-mode-change event with current mode (event.detail)
  • Accepts layout props for mobile and desktop positioning

  Minimal usage:

  <ThemeToggle />

  🔧 Props

  Prop	Type	Default	Description
  mobilePosition	"fixed" | "absolute"	fixed	CSS position for mobile screens.
  desktopPosition	"fixed" | "absolute"	fixed	CSS position for desktop viewports.

  Example usage:

  <ThemeToggle mobilePosition="fixed" desktopPosition="fixed" />

• useThemeAnimationToggle

  A React hook that returns true when the current theme is set to "dark-static". Useful for conditionally disabling animations when the static theme is active.

  Example usage:

  const disableAnimation = useThemeAnimationToggle();

---

🧾 Props Reference

stars

Prop	Type	Default	Description
count	number	150	Number of stars
twinkleDecrease	number	800	How quickly stars twinkle
minRadius	number	0.5	Minimum radius of a star
maxRadius	number	2.0	Maximum radius of a star

clusters

Prop	Type	Default	Description
count	number	3	Number of star clusters
starCount	number	25	Stars per cluster
color	string	rgba(255,255,255,1)	Color of cluster stars
radius	number	60	Radius of each cluster
size	number	1.5	Scale multiplier for cluster stars

planets

Prop	Type	Default	Description
size	number	1.6	Planet size multiplier
glow	number	4	Glow intensity
orbitSpeed	number	0.001	Speed of planetary orbit
orbitRadiusRange	[number, number]	[4, 7]	Min and max orbit radius
density	number	0.92	Number of planets based on density

meteors

Prop	Type	Default	Description
enable	boolean	true	Whether meteors are shown
interval	number	4000	Time between meteor spawns (ms)
length	number	80	Meteor length
glow	number	8	Glow intensity
colors	string[]	See below ▼	Meteor trail colors
speed	number	1	Speed of meteors
trailWidth	number	2.5	Width of the meteor trail
angle	number	135	Meteor angle in degrees
opacity	number	2	Meteor opacity

Default value for meteors.colors

["#ffffff", "rgba(173,216,230, 0.6)", "rgba(255,255,255,0)"];

visual

Prop	Type	Default	Description
disableAnimation	boolean	false	Disables animation (used for dark-static)
hueOptions	string[]	See below ▼	Background hue overlays
parallaxFactor	number	20	Strength of parallax motion
parallaxSmoothing	number	0.05	Smoothing factor for parallax movement
showHueControl	boolean	true	Toggle to show/hide the hue color overlay control panel
mobilePosition	string	fixed	CSS position mode on mobile (fixed or absolute) of hue Control button
desktopPosition	string	fixed	CSS position mode on desktop (fixed or absolute) of hue control button

Default value for hueOptions

[
  "rgba(220, 200, 255, 0.04)",
  "rgba(255, 220, 200, 0.05)",
  "rgba(200, 255, 240, 0.04)",
  "rgba(255, 255, 200, 0.04)",
  "rgba(200, 230, 255, 0.04)",
];

---

🛠 Requirements

• React 18+

• Framer Motion 7+

• Tailwind CSS

• Compatible with any modern React setup (Vite, Next.js, CRA, etc.). Vite is used for development.

• TypeScript supported (but optional)

---

🧭 Use Cases

• Personal portfolios and developer resumes
• Hero sections of landing pages
• Conference or hackathon websites
• Splash screens for games or apps
• Backgrounds for data visualizations or dashboards

---

📄 License

MIT © Shikhar Sinha

---

🤝 Contributing

Contributions, PRs, and feedback are welcome!

Whether it's fixing bugs, adding features, or improving documentation — all help is appreciated. Please open an issue to discuss ideas before large changes.

---

🧑‍💻 Local Dev Setup

To develop locally:

1. Clone the repo:

   git clone https://github.com/Shikhar1504/space-background.git
   cd space-background

2. Install dependencies:

   npm install

3. Build the package:

   npm run build

4. Test in a demo project:

   • Create a new Vite app (e.g. vite-demo)

   • Use npm link to link space-background

   • Import and render in your demo app

---

🌌 Made with ✨ + 🧠

Enjoy building with cosmic vibes!

---

🌍 Used In

Project Name	Link
My Portfolio	shikhar.dev
Your Site?	Submit via PR

Want to be featured here? Open a PR or create an issue with your link!

---

Made with 🪐 stars, ☄️ meteors, and 💫 imagination by @Shikhar1504

````