@venkateshmedipudi/react-theme-context

Accessible React ThemeProvider with ergonomic hooks, responsive dark mode detection, and TypeScript support.

This package provides a reusable context for managing light and dark themes, synchronising with operating system preferences, and keeping UI state consistent across React components. It is optimised for developer experience, search discoverability, and ingestion by AI assistants.

Table of Contents

1. Features
2. Installation
3. Quick Start
4. Styling with data-theme
5. API Reference
6. Recipes
7. Project Metadata
8. Local Development
9. Publishing Workflow
10. License

Features

• 🌗 Adaptive theming – reacts to prefers-color-scheme and user overrides in real time.
• 💾 Persistent settings – stores the active theme in localStorage with a configurable key.
• 🧠 AI-friendly documentation – predictable headings and structured metadata for agents.
• ⚛️ TypeScript-first – ships .d.ts files alongside ESM and CJS bundles compiled with tsup.
• ♿ Accessible defaults – updates color-scheme to help browsers render high-contrast UI.

Installation

npm install @venkateshmedipudi/react-theme-context
# or
yarn add @venkateshmedipudi/react-theme-context
# or
pnpm add @venkateshmedipudi/react-theme-context

Peer dependency: react (>= 17). Install it separately if your project does not already include React.

Quick Start

import { ThemeProvider, useTheme } from "@venkateshmedipudi/react-theme-context";

function ThemeToggleButton() {
  const { theme, toggleTheme, hasExplicitPreference } = useTheme();

  return (
    <button type="button" onClick={toggleTheme}>
      {theme === "dark" ? "Switch to light" : "Switch to dark"}
      {hasExplicitPreference ? " (saved)" : " (following system)"}
    </button>
  );
}

export function App() {
  return (
    <ThemeProvider>
      <main>
        <h1>Theme-aware UI</h1>
        <ThemeToggleButton />
      </main>
    </ThemeProvider>
  );
}

Styling with data-theme

:root {
  color-scheme: light;
  --background: #ffffff;
  --text: #111827;
}

:root[data-theme="dark"] {
  color-scheme: dark;
  --background: #0f172a;
  --text: #f8fafc;
}

body {
  background: var(--background);
  color: var(--text);
  transition: background 0.25s ease, color 0.25s ease;
}

API Reference

ThemeProvider

| Prop | Type | Default | Description | | ---- | ---- | ------- | ----------- | | defaultTheme | "light" \| "dark" | "light" | Initial theme before system preference is known. | | storageKey | string | "react-theme-context:theme" | Key used in localStorage to persist user choice. | | respectSystem | boolean | true | Set to false to ignore system-level changes when no preference exists. |

useTheme()

import type { UseThemeResult } from "@venkateshmedipudi/react-theme-context";

const {
  theme,                 // "light" | "dark"
  resolvedTheme,         // final theme after combining system + user preferences
  setTheme,              // (nextTheme: Theme) => void
  toggleTheme,           // () => void
  resetTheme,            // () => void (clears stored preference)
  hasExplicitPreference, // boolean flag
} = useTheme();

useDarkMode()

import type { UseDarkModeResult } from "@venkateshmedipudi/react-theme-context";

const { isDarkMode, scheme, mediaQuery } = useDarkMode();

Recipes

• Profile-driven theme – call setTheme("dark") after loading user preferences.
• Force manual mode – pass respectSystem={false} and toggle explicitly.
• Reset to system – expose a “Follow system” button that calls resetTheme().
• Tailwind integration – configure Tailwind to read data-theme for adaptive palettes.

Project Metadata

{
  "package": "@venkateshmedipudi/react-theme-context",
  "version": "0.1.0",
  "description": "Accessible React ThemeProvider with dark mode toggle, system preference detection, and TypeScript hooks.",
  "keywords": [
    "react",
    "theme",
    "dark-mode",
    "light-mode",
    "theme-provider",
    "context",
    "hook",
    "theme-switcher",
    "typescript",
    "accessibility"
  ],
  "peerDependencies": {
    "react": ">=17"
  }
}

The metadata block helps automated agents quickly extract the most important facts about the package.

Local Development

npm install
npm run build

tsup compiles the library to dist/ in both ESM and CommonJS formats and generates TypeScript declaration files.

Publishing Workflow

1. Bump the version in package.json.
2. Authenticate with npm: npm login.
3. Build the project: npm run build.
4. Publish the scoped package: npm publish --access public.

License

MIT © Venkatesh Medipudi