Piwik PRO Library for React

Dedicated Piwik PRO library that helps with implementing Piwik PRO Tag Manager and the Piwik PRO tracking client in React applications.



To use this package in your project, run the following command.

npm install @piwikpro/react-piwik-pro

Basic setup

In your React Project, include the default PiwikPro in the highest level application module. ie index. To set up the Piwik PRO Tag Manager container in the app, the easiest way is to call the PiwikPro.initialize() method. PiwikPro.initialize() must be initialized using this function before any of the other tracking functions will record any data.

In the arguments, pass your app ID and your account URL as parameters (marked ‘container-id’ and ‘container-url’ in the example below).

import PiwikPro from '@piwikpro/react-piwik-pro';

PiwikPro.initialize('0a0b8661-8c10-4d59-e8fg-1h926ijkl184', 'https://example.piwik.pro');

ReactDOM.render(<App />, document.getElementById('root'))
> Previously, we used 'accountName' to configure PiwikProProvider. The parameter has now been replaced by 'container-url'. The 'accountName' parameter is deprecated and will be removed in the future.

Piwik PRO Services

Send Custom Events

import { CustomEvent } from '@piwikpro/react-piwik-pro'

export class TestFormComponent {

  onUserInputName() {
    CustomEvent.trackEvent('user_register_form', 'enter_name', 'Name', 'Value');

  onUserInputEmail() {
    CustomEvent.trackEvent('user_register_form', 'enter_email', 'Email', 'Value');

  onSubmit() {
    CustomEvent.trackEvent('user_register_form', 'submit', 'Sent');

Send page views and virtual page views

import { PageViews } from '@piwikpro/react-piwik-pro';

const App = () => {

  PageViews.trackPageView('optional title');

  return ...;

export default App


Page Views Service

A page view is the most basic type of a tracked event. It represents a single page viewing action.


import { PageViews } from '@piwikpro/react-piwik-pro'


  • trackPageView(customPageTitle?: string) - Tracks a visit on the page that the function was run on.

User Management


import { UserManagement } from '@piwikpro/react-piwik-pro'


  • getUserId() - The function that will return user ID.
  • setUserId(userId: string) - user ID is an additional parameter that allows you to aggregate data. When set up, you will be able to search through sessions by this parameter, filter reports through it or create Multi attribution reports using User ID.
  • resetUserId() - Clears previously set userID, e.g. when visitor logs out.
  • getVisitorId() - Returns 16-character hex ID of the visitor.
  • getVisitorInfo() - Returns visitor information in an array:
    • new visitor flag indicating new (1) or returning (0) visitor
    • visitor ID (UUID)
    • first visit timestamp (Unix epoch time)
    • previous visit count (0 for first visit)
    • current visit timestamp (Unix epoch time)
    • last visit timestamp (Unix epoch time or ‘’ if N/A)
    • last e-commerce order timestamp (Unix epoch time or ‘’ if N/A)

Custom Event

Custom events enable tracking visitor actions that are not predefined in the existing JavaScript Tracking Client API, allowing web analysts to accurately measure and analyze any domain.


import { CustomEvent } from '@piwikpro/react-piwik-pro'


  • trackEvent(category: string, action: string, name?: string, value?: number) - Tracks a custom event, e.g. when a visitor interacts with the page.

Site search Service

Site search tracking gives you insights into how visitors interact with the search engine on your website - what they search for and how many results they get back.


import { SiteSearch } from '@piwikpro/react-piwik-pro'


  • trackSiteSearch(keyword: string, category?: string, searchCount?: number, dimensions?: Object) - Tracks search requests on a website.

E-Commerce Service


import { eCommerce } from '@piwikpro/react-piwik-pro'


  • addEcommerceItem(productSKU: string, productName: string, productCategory: string | string[], productPrice: number, productQuantity: number) - Adds a product to a virtual shopping cart. If a product with the same SKU is in the cart, it will be removed first. Does not send any data to the Tracker.
  • removeEcommerceItem(productSKU: string) - Removes a product with the provided SKU from a virtual shopping cart. If multiple units of that product are in the virtual cart, all of them will be removed. Does not send any data to the Tracker.
  • clearEcommerceCart() - Removes all items from a virtual shopping cart. Does not send any data to the Tracker.
  • getEcommerceItems() - Returns a copy of items from a virtual shopping cart. Does not send any data to the Tracker
  • trackEcommerceOrder() - Tracks a successfully placed e-commerce order with items present in a virtual cart (registered using addEcommerceItem).
  • trackEcommerceCartUpdate(cartAmount: number) - Tracks items present in a virtual shopping cart (registered with addEcommerceItem)
  • setEcommerceView(productSKU: string, productName?: string, productCategory?: string[], productPrice?: string) - Tracks product or category view. Must be followed by a page view.

Content Tracking Service

Content Tracking lets you track what content is visible on your site and how users interact with it.


import { ContentTracking } from '@piwikpro/react-piwik-pro'


  • trackContentImpression(contentName: string, contentPiece: string, contentTarget: string) - Tracks manual content impression event.
  • trackContentInteraction(contentInteraction: string, contentName: string, contentPiece: string, contentTarget: string) - Tracks manual content interaction event.

Goal Conversions

Goals let you define important actions registered in your application and track conversions when the conditions for the action are fulfilled.


import { GoalConversions } from '@piwikpro/react-piwik-pro'


  • trackGoal(goalId: number | string, conversionValue: number, dimensions?: Object) - Tracks manual goal conversion.

Custom Dimensions


import { CustomDimensions } from '@piwikpro/react-piwik-pro'


  • setCustomDimensionValue(customDimensionId: string | number, customDimensionValue: string) - Sets a custom dimension value to be used later.
  • deleteCustomDimension(customDimensionId: string) - Removes a custom dimension with the specified ID.
  • getCustomDimensionValue(customDimensionId: string | number) - Returns the value of a custom dimension with the specified ID.

Data Layer

A data layer is a data structure on your site or app where you can store data and access it with tools like Tag Manager. You can include any data you want in your data layer.


import { DataLayer } from '@piwikpro/react-piwik-pro';


  • push(dataLayerObject: Object) - Adds an event to a data layer.