use-react-amplitude

React hooks for Amplitude.

Features

• Small. 27.2 kB (minified and gzipped). Size Limit controls the size.
• Simple.
• Modern. Based on the latest Typescript SDK for Web, but does not required installation. Сan be used with the Typescript SDK.
• Typescript support.

Install

npm install use-react-amplitude

Changelog

https://github.com/Valyay/use-react-amplitude/blob/main/CHANGELOG.md

How to use

First, you must initialize the SDK. Find your Amplitude project's API Key in your project's Settings page and pass the first argument in the function initAmplitude. Your project's API key is required. You can pass an optional user ID and options object in this call. After initialization you can use hooks.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import { initAmplitude } from '@valyay/use-react-amplitude';

// Option 1, initialize with apiKey only
initAmplitude('YOUR_AMPLITUDE_API_KEY');

// Option 2, initialize with user id
initAmplitude('YOUR_AMPLITUDE_API_KEY', '[email protected]');

// Option 3, initialize with options
initAmplitude('YOUR_AMPLITUDE_API_KEY', '[email protected]', your_options);

ReactDOM.render(
    <React.StrictMode>
      <App />
  </React.StrictMode>,
document.getElementById("root"),
);

Track event when component mounts

import React from "react";
import { useTrackOnMount } from '@valyay/use-react-amplitude';

export const Component = () => {

  // Option 1, initialize with event input only
  const {code, event, message} = useTrackOnMount('user_event');

  // Option 2, initialize with event properties
  const {code, event, message} = useTrackOnMount('user_event', {userProp: "foo"});

  // Option 3, initialize with event options
  const {code, event, message} = useTrackOnMount('user_event', {userProp: "foo"}, {insert_id: "test_insert_id"});

  // Hook return code, event and message of event
  const {code, event, message} = useTrackOnMount('user_event', {userProp: "foo"}, {insert_id: "test_insert_id"});

  // console.log(event); // {...}
  // console.log(code); // 200
  // console.log(message); // "Event tracked successfully"

  return <div>Title</div>;

};

Track event when component mounts or dependencies change

import React, { useState } from "react";
import { useTrackOnChange } from '@valyay/use-react-amplitude';

export const Component = () => {

  const [count, setCount] = useState<number>(0);

  // Initialize with event input only
  useTrackOnChange("count increase", [count]);
  
  // Hook return code, event and message of event
  const {code, event, message} = useTrackOnChange("count increase", [count]);

  // console.log(event); // {...}
  // console.log(code); // 200
  // console.log(message); // "Event tracked successfully"

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

};

Track event when only dependencies change

import React, { useState } from "react";
import { useTrackOnUpdate } from '@valyay/use-react-amplitude';

export const Component = () => {

  const [count, setCount] = useState<number>(0);
  
  // Initialize with event input only
  useTrackOnUpdate("count increase", [count]);
  
  // Hook return code, event and message of event
  const {code, event, message} = useTrackOnChange("count increase", [count]);
  // console.log(event); // {...}
  // console.log(code); // 200
  // console.log(message); // "Event tracked successfully"
  
  return (
    <div>
        <button onClick={()=>{setCount(count+1);}}>click</button>
  </div>
  );

};

API

initAmplitude

Wrapper for initialization Amplitude. Full analogue of init.

| Prop | Type | Required | | :-----: | :-----------------------------------------------------------------------------------------------------------: | :------: | | apiKey | string | true | | userId | string | false | | options | BrowserOptions | false |

useTrackOnMount

Hook is called after the component is mounted. Analogue of componentDidMount.

| Prop | Type | Required | | :-------------: | :---------------------: | :------: | | eventInput | string | true | | eventProperties | Record<string, unknown> | false | | eventOptions | EventOptions | false |

useTrackOnChange

The hook is called after mounting a component or changing any of the values in the array. (deep comparison is used)

| Prop | Type | Required | | :-------------: | :---------------------: | :------: | | eventInput | string | true | | dependencies | DependencyList | true | | eventProperties | Record<string, unknown> | false | | eventOptions | EventOptions | false |

useTrackOnUpdate

The hook is called after changing any of the values in the array. Analogue of componentDidUpdate. (deep comparison is used)

| Prop | Type | Required | | :-------------: | :---------------------: | :------: | | eventInput | string | true | | dependencies | DependencyList | true | | eventProperties | Record<string, unknown> | false | | eventOptions | EventOptions | false |