hook-conditional

Dynamic Hook Logic in React, Based on Any Runtime Condition Simplify conditional logic in your components by delegating it to purpose-built hooks mapped to values like roles, flags, environments, or status codes.

🚀 Features

• 🔀 Switch on Any Condition – Support for strings, numbers, booleans, or any discriminant value.
• 🧠 Declarative Hook Selection – Map conditions to custom hooks and let React do the rest.
• ⚡ Fully Compliant – All hooks are called unconditionally, following the Rules of Hooks.
• ✨ Tiny & Typed – Minimal, type-safe API with full IntelliSense support.
• 🛡 Optional Fallback – Gracefully handle unmatched conditions with a fallback hook.

📦 Getting Started

Installation

Install via your preferred package manager:

# npm
npm install hook-conditional

# yarn
yarn add hook-conditional

# pnpm
pnpm add hook-conditional

# bun
bun add hook-conditional

Basic Usage

"use client";

import { useConditionalHook } from "hook-conditional";

const Page = () => {
  const env = process.env.NODE_ENV;

  const value = useConditionalHook(env, {
    development: () => useDevHook(),
    production: () => useProdHook(),
    test: () => useTestHook(),
  });

  return <p>{value}</p>;
};

🔍 API Reference

useConditionalHook(condition, hookMap, fallbackHook?) (TypeScript)

Switches between custom hooks based on a condition. All mapped hooks are always executed to comply with React’s Rules of Hooks, but only the result of the matching hook is returned.

Parameters

• condition (string | number | boolean)
  The runtime value that determines which hook result to return.

• hookMap (Record<string | number, () => TResult>)
  An object where each key corresponds to a possible value of condition, and the value is a hook function to execute.

• fallbackHook (() => TResult, optional)
  A fallback hook to use when no match is found in the map.

Returns

• TResult — The result of the matched hook (or fallback hook if no match is found).

🔒 Security & Provenance

This package is published with NPM Package Provenance, which provides cryptographic proof that the package was built from the source code in this repository using GitHub Actions.

Verifying Package Authenticity

You can verify the package's provenance using:

# Install the package
npm install hook-conditional

# Verify the provenance
npm audit signatures

# Or use the provided verification script
npm run verify-provenance

What This Means

• ✅ Authentic Source: The package was built from this exact repository
• ✅ Secure Build: Built in a trusted GitHub Actions environment
• ✅ Tamper-Proof: Cryptographically signed to prevent supply chain attacks
• ✅ Transparent: You can verify the build process and source code

For more information about NPM Package Provenance, see the official documentation.

💡 Examples

Role-based hook switching

"use client";

import useConditionalHook from "hook-conditional";

const Page = () => {
  const role = useUserRole();

  const permissions: string[] = useConditionalHook(role, {
    guest: () => useGuestPermissions(),
    user: () => useUserPermissions(),
    admin: () => useAdminPermissions(),
  });

  return <div>Permissions: {permissions.join(", ")}</div>;
};

Boolean feature flag

"use client";

import useConditionalHook from "hook-conditional";

const Page = () => {
  const isEnabled = useFeatureFlag("new-ui");

  const ui = useConditionalHook(isEnabled, {
    true: () => useNewUI(),
    false: () => useOldUI(),
  });

  return <>{ui}</>;
};

Numeric condition

"use client";

import useConditionalHook from "hook-conditional";

const Page = () => {
  const status = useStatus();

  const content = useConditionalHook(
    status,
    {
      200: () => useSuccessContent(),
      404: () => useNotFoundContent(),
      500: () => useErrorContent(),
    },
    () => useDefaultContent()
  );

  return <>{content}</>;
};

🛠 Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Open a Pull Request.

Please ensure your code matches the project style and includes relevant tests if applicable.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👨‍💻 Created By

This package is developed and maintained by JP.Coffee. Feel free to reach out or open an issue for any questions or suggestions!