Welcome to @galiprandi/react-tools, a set of simple and intuitive utilities for developing React applications. This package includes key tools that can streamline your development process.

Playground

Try out the components in the playground: @galiprandi/react-tools Playground

Installation

To install use one of the following commands:

npm i @galiprandi/react-tools

pnpm i @galiprandi/react-tools

yarn add @galiprandi/react-tools

Components:

• <Form />: A component that wraps the form HTML tag and provides a simple way to create forms in your React application. Example

• <Input />: A reusable input component that provides a consistent user experience. Example

• <DateTime />: A reusable input component with type="datetime-local" that use dates in RFC 3339 format. Example

• <Dialog />: A component that wraps the dialog HTML tag and provides a simple way to create accessibility dialogs and modals in your React application. Example

• <Observer />: A component allows you to track when an element enters or exits the viewport. This is useful for lazy loading images, infinite scrolling, and more. Example

Hooks:

• useDebounce(): A hook that takes two arguments, value and delay, and return a debounced value. Example

Components

Form component

A component that wraps the form HTML tag and provides a simple way to create forms in your React application.

Adicional Props:

• onSubmitValues: Callback function that is called when the form is submitted and recibe a object with the form values.
• filterEmptyValues: Boolean, defines if the empty values are filtered from the object passed to the onSubmitValues callback. (Default: false)

Example:

import { Form, Input } from '@galiprandi/react-tools'
import { useState } from 'react'

export const FormExample = () => {
    const [values, setValues] = useState<MyFormValues>()

    return (
        <section>
            <hr />
            <h2>Form</h2>
            <Form<MyFormValues>
                onSubmitValues={setValues}
                filterEmptyValues={true}
            >
                <fieldset>
                    <legend>Form Example</legend>
                    <Input
                        name="username"
                        label="username"
                        placeholder="Username"
                    />
                    <br />
                    <Input
                        name="password"
                        label="password"
                        placeholder="Password"
                        type="password"
                    />
                    <br />
                    <button type="submit">Login</button>
                </fieldset>
            </Form>
            <p>
                <br />
                onChangeISOValue: <code>{JSON.stringify(values)}</code>
            </p>
        </section>
    )
}

type MyFormValues = {
    username: string
    password: string
}

Input component

A simple wrapper around the native input element. It accepts all the same props as the native input element and adds a few additional props for convenience.

Adicional Props:

• label: A label for the input element. If provided, we add a label element with the provided text.
• onChangeValue: A callback function that is called when the input value changes
• onChangeDebounce: A callback function that is called when the input value changes after the debounce delay.
• debounceDelay: The delay in milliseconds for the debounce.
• className: A class name to apply to the input element. If a label is provided, the class name is applied to the label and input elements.
• transform: The type of transformation to apply to the input value. Options include "toUpperCase", "toLowerCase", "capitalize", "titleCase", "snakeCase", "onlyNumbers", "onlyLetters", "onlyEmail" and "onlyAlphanumeric"
• transformFn: A custom function to apply to the input value. This function takes a string as input and returns a string as output. If both transform and transformFn are provided, the transformFn function will take precedence.
• datalist: An array of strings to use as options in a datalist element.

Example:

import { useState } from "react";
import { Input, type InputProps } from '@galiprandi/react-tools';

export const InputExample = () => {
  const [value, setValue] = useState<InputProps["value"]>();
  const [valueDebounced, setValueDebounced] = useState<InputProps["value"]>();

  return (
    <section>
      <h2>Input</h2>

      <Input
        type="text"
        placeholder="Enter your name and last name"
        // Custom attributes
        label="Name and Last Name"
        className="my-custom-input"
        value={value}
        onChangeValue={setValue}
        onChangeDebounce={setValueDebounced}
        debounceDelay={1000}
        transform="titleCase"
        datalist={['John Doe', 'Jane Doe', 'John Smith']}
      />
      <p>
        Transformed value: <code>{value}</code>
        <br />
        Debounced value (1s): <code>{valueDebounced}</code>
      </p>
    </section>
  );
};

DateTime component

A simple wrapper around the native input element with type="datetime-local". It accepts all the same props as the native input element and adds a few additional props for convenience.

Adicional Props:

• label: A label for the input element. If provided, we add a label element with the provided text.
• className: A class name to apply to the input element. If a label is provided, the class name is applied to the label and input elements.
• onChangeValue: A callback function that is called when the input value changes.
• onChangeISOValue: A callback function that is called when the input value changes and returns the date in RFC 3339 format.
• isoValue: The date in RFC 3339 format.
• Any other prop that the our Input component accepts (like onChangeDebounce, transform and transformFn).

Example:

import { useState } from 'react';
import { DateTime, type DateTimeProps } from '@galiprandi/react-tools';

export const DateTimeExample = () => {
  const now = new Date().toISOString();
  const [isoValue, setIsoValue] = useState<DateTimeProps['isoValue']>(now);

  return (
    <section>
      <hr />
      <h2>DateTime</h2>
      <DateTime
        // Custom attributes
        isoValue={isoValue}
        label="Choice your birthday"
        onChangeISOValue={setIsoValue}
      />
      <p>
        onChangeISOValue: <code>{isoValue}</code>
      </p>
    </section>
  );
};

Dialog component

A component that wraps the dialog HTML tag and provides a simple way to create accessibility dialogs and modals in your React application.

Adicional Props:

• isOpen: Boolean, defines if the dialog is open or closed. (Optional)
• behavior: 'dialog' | 'modal', defines the behavior of the dialog. (Default: 'modal')
• onOpen: Callback function executed when the dialog is opened. (Optional)
• onClose: Callback function executed when the dialog is closed. (Optional)
• children: ReactNode, the content of the dialog. (Optional)
• opener: ReactNode, the element that opens the dialog. (Optional)

Example:

import { Dialog } from '@galiprandi/react-tools'

export const DialogExample = () => {
    return (
        <section>
            <hr />
            <h2>Dialog</h2>

            <Dialog
                // Custom attributes
                behavior="modal"
                opener={<button>Toggle Dialog</button>}
                onOpen={() => console.info('Dialog opened')}
                onClose={() => console.info('Dialog closed')}
            >
                <h2>Hello there 👋</h2>
                <p>This is a dialog example.</p>
                <p>
                    For information on how to use html dialogs, or styling them,
                    <a
                        href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog"
                        target="_blank"
                        rel="noopener noreferrer"
                    >
                        {' '}
                        check documentation on MDN website
                    </a>
                </p>
            </Dialog>
        </section>
    )
}

Observer component

A component that allows you to track when an element enters or exits the viewport. This is useful for lazy loading images, infinite scrolling, and more.

Adicional Props:

• children: ReactNode, the content of the observer.
• onAppear: Callback function executed when the element enters the viewport. (Optional)
• onDisappear Callback function executed when the element exits the viewport. (Optional)
• wrapper: HTMLElement, the element that is used as wrapper of children. (Default: 'div')
• root: HTMLElement, the element that is used as the viewport for checking visibility of the target. (Optional)
• rootMargin Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left). The values can be percentages. (Optional)
• threshold Number, a number between 0 and 1 indicating the percentage of the target's visibility the observer's callback should be executed. (Default: 0)

Example:

import { Observer } from '@galiprandi/react-tools'
import { useState } from 'react'

export const ObserveExample = () => {
    const [inScreen, setInScreen] = useState<number[]>([])
    const images = Array.from({ length: 5 }, (_, i) => i + 1)

    return (
        <section>
            <hr />
            <h2>Observer</h2>
            <p>
                <small>
                    A component that allows you to track when an element enters
                    or exits the viewport. This is useful for lazy loading
                    images, infinite scrolling, and more.
                </small>
            </p>
            <div
                style={{
                    position: 'sticky',
                    top: 0,
                    right: 0,
                    fontSize: 20,
                    background: '#283618',
                    padding: 15,
                }}
            >
                Images in screen: {inScreen.join(' | ')}
            </div>
            <br />
            {images.map((i) => (
                <Observer
                    key={i}
                    wrapper="p"
                    onAppear={() =>
                        setInScreen((prev) => Array.from(new Set([...prev, i])))
                    }
                    onDisappear={() =>
                        setInScreen((prev) => prev.filter((item) => item !== i))
                    }
                    threshold={0.5}
                >
                    <>
                        <img
                            src={`https://picsum.photos/500/500?random=${i}`}
                            loading="lazy"
                            alt="Free image"
                            width={500}
                            height={500}
                        />
                        <br />
                    </>
                </Observer>
            ))}
        </section>
    )
}

Hooks

useDebounce hook

A simple hook that takes two arguments, value and delay, and returns a debounced value. Its used internally by some components, but you can use it in your custom hooks or components.

Example:

import { useDebounce } from '@galiprandi/react-tools'
import { useState } from 'react'

export const DebounceExample = () => {
    const [value, setValue] = useState<string>()
    const debouncedValue = useDebounce(value, 1000)

    return (
        <section>
            <hr />
            <h2>useDebounce</h2>

            <input
                type="text"
                placeholder="Type something..."
                value={value}
                onChange={(e) => setValue(e.target.value)}
            />
            <p>
                Value: <code>{value}</code>
                <br />
                Debounced value (1s): <code>{debouncedValue}</code>
            </p>
        </section>
    )
}

Contribution

Contributions are welcome! To contribute:

1. Fork this repository.
2. Create a branch with a meaningful description.
3. Make the desired changes.
4. Update the documentation if necessary.
5. Open a Pull Request to the main branch.

If you find an issue or have a suggestion to improve the project, feel free to open an issue.

License

This project is licensed under the MIT License.