✨ Simple, composable & accessible utilities for React development.

• Overview
• Installation
• Components
  • AsyncBlock
  • Form
  • Input
  • DateTime
  • Dialog
  • Observer
  • LazyRender
• Hooks
  • useDebounce
  • useTimer
  • useList
• Accessibility & Performance
• FAQ
• License

@galiprandi/react-tools is a lightweight, dependency-free utility library for React. It provides reusable components and hooks to simplify development and improve accessibility — no configuration needed.

👉 Live Playground

npm install @galiprandi/react-tools
# or
yarn add @galiprandi/react-tools
# or
pnpm add @galiprandi/react-tools

Description
Declarative component to render async data with loading, success, and error states. Automatically cancels in-flight requests when dependencies change.

Example

<AsyncBlock
  promiseFn={() => fetch(`/api/user`).then(res => res.json())}
  pending={<p>Loading...</p>}
  success={(data) => <p>Welcome {data.name}</p>}
  error={(err) => <p>Error: {(err as Error).message}</p>}
  timeOut={5000}
  deps={[userId]}
/>

Props

Description
Enhanced <form> element that automatically gathers and returns values on submit.

Example

<Form<{ username: string }> onSubmitValues={console.log} filterEmptyValues>
  <Input name="username" label="Username" />
  <button type="submit">Submit</button>
</Form>

Props

Description
Custom input component supporting transformations, debounce, datalist, and more.

Example

<Input
  label="Email"
  name="email"
  placeholder="Enter your email"
  transform="onlyEmail"
  onChangeValue={(val) => console.log(val)}
  debounceDelay={500}
/>

Props

Description
A wrapper around <input type="datetime-local" /> that handles ISO string conversion.

Example

<DateTime
  label="Appointment"
  isoValue={value}
  onChangeISOValue={setValue}
/>

Props

Description
Accessible dialog/modal component built on top of the native <dialog> element.

Example

<Dialog
  behavior="modal"
  opener={<button>Open Modal</button>}
  onClose={() => console.log('Closed')}
>
  <p>This is a dialog!</p>
</Dialog>

Props

Description
Tracks whether a child element is visible in the viewport using IntersectionObserver.

Example

<Observer onChange={(visible) => console.log(visible)}>
  <div>Watch me appear!</div>
</Observer>

Props

Description
Only renders children when they become visible in the viewport.

Example

<LazyRender placeholder={<span>Loading...</span>}>
  <img src="/heavy-image.jpg" alt="Lazy" />
</LazyRender>

Props

Description
A React hook that returns a debounced version of a value. Useful for search input, filters, etc.

Example

const debouncedSearch = useDebounce(searchTerm, 500);

Props

Returns
Debounced version of the value (T).

Description Managing timers like setTimeout and setInterval directly in React components can be complex, often leading to issues like memory leaks, unexpected behavior during re-renders, or difficulties in cancellation when components unmount.

The useTimer hook abstracts this complexity, providing a safe, declarative, and easy-to-use way to work with various types of timers. It ensures automatic cleanup, integrates with component lifecycles, and offers event callbacks for monitoring timer status, including progress for longer durations.

Features

• Automatic Cleanup: Timers are automatically cleared when the component using the hook unmounts, preventing memory leaks.
• Lifecycle Events: Receive notifications when a timer is set, cancelled, completes, or reports progress.
• Flexible Scheduling: Set timers by milliseconds, a future Date object, or as limited intervals.
• Simplified Control: Clear any active timer with a single method call.

Parameters (options)

Returns An object containing control methods and status/info getters.

Example

This example demonstrates how useTimer simplifies scheduling an action for a specific future targetDate and automatically handles cleanup, while utilizing event callbacks to monitor its state.

import { useEffect } from 'react';
import { useTimer } from '@galiprandi/react-tools';

function FutureExecution({ targetDate }: { targetDate: Date }) {
  const { setTimeoutDate, clearTimer } = useTimer({
    onSetTimer: (id) => console.log(`Timer ID ${id} set for future execution`),
    onTimerComplete: (id) => console.log(`Timer ID ${id} completed!`),
    onCancelTimer: (id) => console.log(`Timer ID ${id} cancelled!`),
    onProgress: (progress) =>
      console.log(`Progress: ${Math.round(progress * 100)}%`),
  });

  useEffect(() => {
    console.log(`Scheduling action for: ${targetDate.toLocaleTimeString()}`);

    setTimeoutDate(() => {
      // Do something here, like a fake fetch request
      console.log("--- Fake fetch executed! ---");
    }, targetDate);

    // ⚠️ Remember to clear the timer when the component unmounts or when the targetDate changes
    return () => {
      console.log('Component unmounting or targetDate change, clearing timer.');
      clearTimer();
    };
  }, [setTimeoutDate, clearTimer, targetDate]);

  return (
    <div>
      <p>Check the console for timer messages.</p>
    </div>
  );
}

Description A React hook to simplify managing array state in components. It provides immutable helper methods for common operations like adding, inserting, removing, updating, finding, and counting items based on index or item properties, reducing boilerplate compared to manual state updates.

Parameters

Returns An object containing the current array state (list) and helper functions to modify or query it immutably.

All components follow accessibility best practices:

• ✅ Dialog uses proper ARIA roles and keyboard focus control.
• ✅ Input supports labeling, aria attributes, and datalists.
• ✅ LazyRender and Observer use IntersectionObserver to optimize rendering.

Q: Is this compatible with React Native?
A: No, this library is intended for use in React DOM (web).

Q: Can I style components with Tailwind or CSS modules?
A: Yes, components are unstyled and fully customizable.

Q: Does it support SSR or work in Next.js?
A: Yes, all components are compatible with SSR environments.

Q: How can I report a bug or request a new feature?
A: Open an issue on the GitHub repo.

MIT © @galiprandi