# gtm-react-hook

> Easy-to-use React hooks for Google Tag Manager

Latest version **1.0.1** (published 2025-02-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install gtm-react-hook
pnpm add gtm-react-hook
yarn add gtm-react-hook
bun add gtm-react-hook
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2025-02-21 |
| First published | 2024-01-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 34.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Valerii Shelihan |
| Maintainers | mara1esh |
| Keywords | react, hooks, analytics, gtm, google tag manager, typescript |

## Links

- npm: https://www.npmjs.com/package/gtm-react-hook
- Repository: https://github.com/mara1esh/gtm-react-hook
- Homepage: https://github.com/mara1esh/gtm-react-hook#readme
- Issues: https://github.com/mara1esh/gtm-react-hook/issues
- npm.io page: https://npm.io/package/gtm-react-hook

## Dependencies (1)

- [react](https://npm.io/package/react.md) ^19.0.0

## Recent versions

- 1.0.1 (latest) — 2025-02-21
- 1.0.0 — 2025-02-21
- 0.0.17 — 2024-07-02
- 0.0.16 — 2024-04-23
- 0.0.15 — 2024-04-23
- 0.0.14 — 2024-04-23
- 0.0.13 — 2024-04-17
- 0.0.12 — 2024-04-17
- 0.0.11 — 2024-04-17
- 0.0.10 — 2024-04-17
- 0.0.9 — 2024-04-17
- 0.0.8 — 2024-01-25
- 0.0.7 — 2024-01-25
- 0.0.6 — 2024-01-25
- 0.0.5 — 2024-01-23
- … 5 more at https://npm.io/package/gtm-react-hook/versions

## README

# 🚀 gtm-react-hook: Easy-to-use React hooks for Google Tag Manager

A lightweight, fully typed React hook library for seamless Google Tag Manager (GTM) integration.

---

## 🎯 Features

✅ Simple & intuitive React hooks
✅ Fully typed with TypeScript
✅ Tiny bundle size (~1kB)
✅ Customizable GTM configuration
✅ Zero external dependencies (only React 19)
✅ Built-in event logging
✅ Test coverage ensured

---

## 📦 Installation

```sh
# Using npm
npm install gtm-react-hook

# Using yarn
yarn add gtm-react-hook

# Using pnpm
pnpm install gtm-react-hook
```

---

## ⚡ Quickstart

```tsx
import { useEffect } from "react";
import { useGTM } from "gtm-react-hook";
import { useLocation } from "react-router-dom";

const App = () => {
  const { runGTM, eventGTM } = useGTM();
  const { pathname } = useLocation();

  useEffect(() => {
    runGTM({
      tagId: "GTM-XXXXXXX", // Provide your GTM Tag ID
    });
  }, []);

  useEffect(() => {
    eventGTM("page_view", { pathname });
  }, [pathname]);

  return <>...</>;
};
```

---

## 🔍 API Reference

### 🏗 `useGTM()`

```tsx
const { runGTM, eventGTM } = useGTM();
```

#### `runGTM({ tagId, dataLayerName, environment, domain, script, nonce, devMode })`

- **tagId** *(required)* – Your GTM measurement ID.
- `dataLayerName` – Custom name for `dataLayer` object.
- `environment` – GTM environment parameters (`gtm_auth`, `gtm_preview`).
- `domain` – Custom GTM domain.
- `script` – Custom GTM script name.
- `nonce` – Security nonce.
- `devMode` – Enables logging for GTM initialization & events.

#### `eventGTM(eventName: string, data?: object)`

- **eventName** *(required)* – Name of the event.
- `data` – Payload for the dataLayer (e.g., action, URL, customer ID, etc.).

---

## 📖 Usage Examples

### 📊 Page Tracking

```tsx
const { eventGTM } = useGTM();
const { pathname } = useLocation();

useEffect(() => {
  eventGTM("page_view", { pathname });
}, [pathname]);
```

### 🎯 Track Custom Events

```tsx
const { eventGTM } = useGTM();

const saveCustomerInfo = (customer) => {
  eventGTM("customer_info", {
    customerId: customer.customerId,
    customerRegion: customer.customerRegion,
  });
};

return <button onClick={saveCustomerInfo}>Submit</button>;
```

### 🛠 Custom Data Layer Name

```tsx
const { runGTM } = useGTM();

useEffect(() => {
  runGTM({
    gtmId: "GTM-XXXXXXX",
    dataLayerName: "myGTMLayer", // Events stored in `window.myGTMLayer`
  });
}, []);
```

### 🔒 Install GTM Only After User Consent

```tsx
const { runGTM } = useGTM();

useEffect(() => {
  if (isUserConfirmAnalytics) {
    runGTM({
      gtmId: "GTM-XXXXXXX",
    });
  }
}, [isUserConfirmAnalytics]);
```

### 🛠 Enable Debugging & Logging

```tsx
const { runGTM } = useGTM();

useEffect(() => {
  runGTM({
    gtmId: "GTM-XXXXXXX",
    devMode: true, // Enables GTM logs in browser console
  });
}, []);
```

---

## ❤️ Contributing

We welcome contributions! Feel free to submit issues and PRs to make this library even better.

---

## 📜 License

This project is licensed under the [MIT License](LICENSE).

---

### 🚀 Happy tracking with `gtm-react-hook`! 🎉

---
_Source: https://npm.io/package/gtm-react-hook · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._