Skip to content

permafrost-dev/react-ray

Repository files navigation

react-ray

card

The official React integration for the Ray app by Spatie.

test status npm version license coverage

Installation

You can install the package via npm:

npm install react-ray

Usage

react-ray supports React 16+ and provides several hooks:

  • useRay - send data to the Ray app whenever it updates.
  • useRayWithElement - send the contents of an element ref to the Ray app, optionally updating the item in place when its dependencies change.
  • useRayInstance - access the Ray instance directly.

useRay()

To send data to Ray whenever it updates, use the useRay hook along with the type option to specify the type of data you are sending. The boolean replace option can be used to update the Ray item in place when its dependencies change. The default value for replace is false.

Valid types are image, json, html, text, or xml. See the node-ray documentation for more information on these types.

import { useRay } from 'react-ray';
import { useEffect, useState } from 'react';

const MyComponent = () => {
    const [count, setCount] = useState(0);

    useRay(count, { type: 'text', replace: true });

    return (
        <button onClick={() => setCount(count + 1)}>
            Click me
        </button>
    );
};

useRayWithElement()

To send the contents of a ref to the Ray app in a sequential manner (each dependency change sends a new item), set the replace option to false:

import { useRayWithElement } from 'react-ray';
import { useRef, useState } from 'react';

const MyComponent = () => {
    const [count, setCount] = useState(0);
    const countRef = useRef(null);

    useRayWithElement(countRef, [count], { replace: false });

    return (
        <div>
            <div ref={countRef}>{count}</div>
            <button onClick={() => setCount(count + 1)}>
                Click me
            </button>
        </div>
    );
};

react-ray-02

To update the Ray item in place that was sent with the contents of a ref when its dependencies change, set the replace option to true or omit it:

import { useRayWithElement } from 'react-ray';
import { useRef, useState } from 'react';

const MyComponent = () => {
    const [count, setCount] = useState(0);
    const countRef = useRef(null);

    useRayWithElement(countRef, [count], { replace: true });
    // or
    // useRayWithElement(countRef, [count]);

    return (
        <div>
            <div ref={countRef}>{count}</div>
            <button onClick={() => setCount(count + 1)}>
                Click me
            </button>
        </div>
    );
};

react-ray-01

useRayInstance()

To access the Ray instance directly, use the useRayInstance hook:

import { useRayInstance } from 'react-ray';

const MyComponent = () => {
    const ray = useRayInstance();

    ray('hello world');

    return (
        <div>
            <button onClick={() => ray('hello world')}>
                Click me
            </button>
        </div>
    );
};

Setup

npm install

npm run dev

Testing

react-ray uses Jest for unit tests. To run the test suite:

npm run test


Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.