README.md

use-clarity

A React Clarity integration powered by hooks.

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