Features

• Hooks
• Written in TypeScript
• Documented, self explaining methods

Installation

# npm
npm install use-clarity

# yarn
yarn add use-clarity

Quickstart

import * as React from 'react';

import { ClarityProvider, useClarity } from 'use-clarity';

const CLARITY_PROJECT_ID = 'your-clarity-project-id';

const App = () => (
  <ClarityProvider clarityId={CLARITY_PROJECT_ID}>
    <HomePage />
  </ClarityProvider>
);

const HomePage = () => {
  const { userId } = useUserContext();
  const { identify } = useClarity();

  React.useEffect(() => {
    identify(userId);
  }, [userId]);

  return <div>Hi I'm a homepage</div>;
};

Context

This library is a React abstraction of Clarity. use-clarity tries to keep as close as a one-on-one abstraction of the "vanilla" Clarity functionality.

Links

• API
• TypeScript

API

• ClarityProvider
• useClarity

ClarityProvider

ClarityProvider is used to initialize the window.clarity instance.

Place the ClarityProvider as high as possible in your application. This will make sure you can call useClarity anywhere.

Props

| name | type | description | required | default | | --------- | ------ | ------------------ | -------- | ------- | | clarityId | string | clarity project id | true | |

Example

const App = () => {
  return (
    <ClarityProvider clarityId={CLARITY_PROJECT_ID}>
      <p>Hi there, I am a child of the ClarityProvider</p>
    </ClarityProvider>
  );
};

useClarity

Used to retrieve all methods bundled with Clarity. These are based on the official Clarity API docs and Clarity Identify API docs. We provide full access to the internals, with additional helper methods.

Make sure ClarityProvider is wrapped around your component when calling useClarity().

Remark - You can't use useClarity() in the same component where ClarityProvider is initialized.

API

| name | type | description | | ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | currentSessionUrl | string? | the url for the current session | | clarityUserId | string? | the current clarity id of the user | | currentSessionId | string? | the current session id | | upgrade | (key: string) => void | prioritize specific types of sessions for recording | | consent | () => void | set consent | | event | (name: string, value: string) => void | send custom events | | set | (variable: string, value: string| string[]) => void; | add custom tags | | identify | (userId: string, sessionId?: string, pageId?: string, userHint?: string) => void | customise the ids | | metadata | (callback: Data.MetadataCallback, wait?: boolean) => void | internal | | signal | (callback: Data.SignalCallback) => void | internal | | start | (config?: Core.Config) => void | internal | | stop | () => void | internal | | pause | () => void | internal | | resume | () => void | internal |

Next Up

• [ ] Add tests
• [ ] Add more examples