Choose a version:

useAnalytics

A hook that provides access to the analytics provider context. Must be a descendent of Analytics.Provider.

Anchor to returnsReturns

Anchor to canTrack canTrack () => boolean: A function to tell you the current state of if the user can be tracked by analytics. Defaults to Customer Privacy API's window.Shopify.customerPrivacy.analyticsProcessingAllowed().
Anchor to cart cart UserCart |: The current cart state. You can overwrite the type by passing a generic
Anchor to customData customData Record<string, unknown>: The custom data passed in from the AnalyticsProvider.
Anchor to prevCart prevCart UserCart |: The previous cart state. You can overwrite the type by passing a generic
Anchor to publish publish: A function to publish an analytics event.
Anchor to register register (key: string) => { ready: () => void; }: A function to register with the analytics provider. It holds the first browser load events until all registered key has executed the supplied ready function. See example register usage.
Anchor to shop shop Promise< | null> | | null: The shop configuration required to publish events to Shopify.
Anchor to subscribe subscribe: A function to subscribe to analytics events.

DefaultCart

Promise<CartReturn | null> | CartReturn | null

CartReturn

Cart & {
  errors?: StorefrontApiErrors;
}

Cart

attributes

The cart's attributes.

{ __typename?: "Attribute"; key?: string; value?: string; }[]

buyerIdentity
The cart's buyer identity.
```
CartType['buyerIdentity']
```
checkoutUrl
The checkout URL for the cart, if the cart has been created in the Storefront API.
```
string
```
cost
The cost for the cart, including the subtotal, total, taxes, and duties.
```
CartType['cost']
```

discountCodes

The discount codes applied to the cart.

{ __typename?: "CartDiscountCode"; applicable?: boolean; code?: string; }[]

id
The cart's ID if it has been created through the Storefront API.
```
string
```

lines

The cart lines.

Array<CartLine | ComponentizableCartLine>

note
The cart's note.
```
string
```
totalQuantity
The total number of items in the cart, across all lines. If there are no lines, then the value is 0.
```
number
```

StorefrontApiErrors

JsonGraphQLError[] | undefined

JsonGraphQLError

extensions
Reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents.
```
{ [key: string]: unknown; }
```
locations
If an error can be associated to a particular point in the requested GraphQL document, it should contain a list of locations.
```
{ line: number; column: number; }[]
```
message
```
string
```
name
```
string
```
path
If an error can be associated to a particular field in the GraphQL result, it _must_ contain an entry with the key `path` that details the path of the response field which experienced the error. This allows clients to identify whether a null result is intentional or caused by a runtime error.
```
(string | number)[]
```
stack
```
string
```

AnalyticsContextPublishForDoc

PublishPageView | PublishProductView | PublishCollectionView | PublishCartView | PublishSearchView | PublishCartUpdated | PublishProductAddedToCart | PublishProductRemovedFromCart | PublishCustomEvent

PublishPageView

event
```
"page_viewed"
```
payload
```
PageViewPayload
```

returns

void

PageViewPayload

UrlPayload & BasePayload

UrlPayload

url
The url location of when this event is collected.
```
string
```

BasePayload

customData
The custom data passed in from the `AnalyticsProvider`.
```
Record<string, unknown>
```
shop
The shop data passed in from the `AnalyticsProvider`.
```
ShopAnalytics | null
```

ShopAnalytics

acceptedLanguage
The language code that is being displayed to user.
```
LanguageCode
```
currency
The currency code that is being displayed to user.
```
CurrencyCode
```
hydrogenSubchannelId
The Hydrogen subchannel ID generated by Oxygen in the environment variable.
```
string | '0'
```
shopId
The shop ID.
```
string
```

CurrencyCode

Supports CurrencyCode from both Storefront API and Customer Account API. The APIs may have different CurrencyCode enums (e.g., Customer Account API added USDC in 2025-10, but Storefront API doesn't support USDC in 2025-10). This union type ensures useMoney works with data from either API.

StorefrontApiCurrencyCode | CustomerAccountApiCurrencyCode

PublishProductView

event
```
"product_viewed"
```
payload
```
ProductViewPayload
```

returns

void

ProductViewPayload

ProductsPayload & UrlPayload & BasePayload

ProductsPayload

products
The products associated with this event.
```
Array<ProductPayload & OtherData>
```

ProductPayload

id
The product id.
```
string
```
price
The displaying variant price.
```
string
```
productType
The product type.
```
string
```
quantity
The quantity of product.
```
number
```
sku
The product sku.
```
string
```
title
The product title.
```
string
```
variantId
The displaying variant id.
```
string
```
variantTitle
The displaying variant title.
```
string
```
vendor
The product vendor.
```
string
```

OtherData

PublishCollectionView

event
```
"collection_viewed"
```
payload
```
CollectionViewPayload
```

returns

void

CollectionViewPayload

CollectionPayload & UrlPayload & BasePayload

CollectionPayload

collection
```
CollectionPayloadDetails
```

CollectionPayloadDetails

handle
The collection handle.
```
string
```
id
The collection id.
```
string
```

PublishCartView

event
```
"cart_viewed"
```
payload
```
CartViewPayload
```

returns

void

CartViewPayload

CartPayload & UrlPayload & BasePayload

CartPayload

cart
The current cart state.
```
CartReturn | null
```
prevCart
The previous cart state.
```
CartReturn | null
```

PublishSearchView

event
```
"search_viewed"
```
payload
```
SearchViewPayload
```

returns

void

SearchViewPayload

SearchPayload & UrlPayload & BasePayload

SearchPayload

searchResults
The search results
```
any
```
searchTerm
The search term used for the search results page
```
string
```

PublishCartUpdated

event
```
"cart_updated"
```
payload
```
CartUpdatePayload
```

returns

void

CartUpdatePayload

CartPayload & BasePayload & OtherData

PublishProductAddedToCart

event
```
"product_added_to_cart"
```
payload
```
CartLineUpdatePayload
```

returns

void

CartLineUpdatePayload

CartLinePayload & CartPayload & BasePayload & OtherData

CartLinePayload

currentLine
The current state of the cart line that got updated.
```
CartLine | ComponentizableCartLine
```
prevLine
The previous state of the cart line that got updated.
```
CartLine | ComponentizableCartLine
```

PublishProductRemovedFromCart

event
```
"product_removed_from_cart"
```
payload
```
CartLineUpdatePayload
```

returns

void

PublishCustomEvent

event
```
`custom_${string}`
```
payload
```
OtherData
```

returns

void

AnalyticsContextSubscribeForDoc

SubscribePageView | SubscribeProductView | SubscribeCollectionView | SubscribeCartView | SubscribeSearchView | SubscribeCartUpdated | SubscribeProductAddedToCart | SubscribeProductRemovedFromCart | SubscribeCustomEvent

SubscribePageView

event
```
"page_viewed"
```
callback
```
(payload: PageViewPayload) => void
```

returns

void

SubscribeProductView

event
```
"product_viewed"
```
callback
```
(payload: ProductViewPayload) => void
```

returns

void

SubscribeCollectionView

event
```
"collection_viewed"
```

callback

(payload: CollectionViewPayload) => void

returns

void

SubscribeCartView

event
```
"cart_viewed"
```
callback
```
(payload: CartViewPayload) => void
```

returns

void

SubscribeSearchView

event
```
"search_viewed"
```
callback
```
(payload: SearchViewPayload) => void
```

returns

void

SubscribeCartUpdated

event
```
"cart_updated"
```
callback
```
(payload: CartUpdatePayload) => void
```

returns

void

SubscribeProductAddedToCart

event
```
"product_added_to_cart"
```

callback

(payload: CartLineUpdatePayload) => void

returns

void

SubscribeProductRemovedFromCart

event
```
"product_removed_from_cart"
```

callback

(payload: CartLineUpdatePayload) => void

returns

void

SubscribeCustomEvent

event
```
`custom_${string}`
```
callback
```
(payload: OtherData) => void
```

returns

void

Examples

import {useAnalytics} from '@shopify/hydrogen';

import {useEffect} from 'react';

export function CustomAnalytics() {

const {subscribe, register} = useAnalytics();

const {ready} = register('CustomAnalytics'); // unique string identifier

useEffect(() => {

// Triggers on every page navigation

subscribe('page_viewed', (data) => {

console.log('CustomAnalytics - Page viewed:', data);

});

// Triggers on a page that uses `<Analytics.ProductView>`

subscribe('product_viewed', (data) => {

console.log('CustomAnalytics - Product viewed:', data);

});

// Triggers on a page that uses `<Analytics.CollectionView>`

subscribe('collection_viewed', (data) => {

console.log('CustomAnalytics - Collection viewed:', data);

});

// Triggers on a page that uses `<Analytics.CartView>`

subscribe('cart_viewed', (data) => {

console.log('CustomAnalytics - Cart viewed:', data);

});

// Triggers on a page that uses `<Analytics.SearchView>`

subscribe('search_viewed', (data) => {

console.log('CustomAnalytics - Search viewed:', data);

});

// Triggers on a page that uses `<Analytics.CustomView type="custom_promotion_viewed">`

subscribe('custom_promotion_viewed', (data) => {

console.log('CustomAnalytics - Promotion viewed:', data);

});

// Triggers when the cart is updated

subscribe('cart_updated', (data) => {

console.log('CustomAnalytics - Cart updated:', data);

});

// Triggers when an existing cart line increases in quantity or a new cart line is added

subscribe('product_added_to_cart', (data) => {

console.log('CustomAnalytics - Product added to cart:', data);

});

// Triggers when an existing cart line decreases in quantity or a cart line is removed

subscribe('product_removed_from_cart', (data) => {

console.log('CustomAnalytics - Product removed from cart:', data);

});

// Register the CustomAnalytics component as ready

ready();

}, []);

return null;

}

Examples

Example

JavaScript

import {useAnalytics} from '@shopify/hydrogen';
import {useEffect} from 'react';

export function CustomAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register('CustomAnalytics'); // unique string identifier

  useEffect(() => {
    // Triggers on every page navigation
    subscribe('page_viewed', (data) => {
      console.log('CustomAnalytics - Page viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.ProductView>`
    subscribe('product_viewed', (data) => {
      console.log('CustomAnalytics - Product viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CollectionView>`
    subscribe('collection_viewed', (data) => {
      console.log('CustomAnalytics - Collection viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CartView>`
    subscribe('cart_viewed', (data) => {
      console.log('CustomAnalytics - Cart viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.SearchView>`
    subscribe('search_viewed', (data) => {
      console.log('CustomAnalytics - Search viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CustomView type="custom_promotion_viewed">`
    subscribe('custom_promotion_viewed', (data) => {
      console.log('CustomAnalytics - Promotion viewed:', data);
    });

    // Triggers when the cart is updated
    subscribe('cart_updated', (data) => {
      console.log('CustomAnalytics - Cart updated:', data);
    });

    // Triggers when an existing cart line increases in quantity or a new cart line is added
    subscribe('product_added_to_cart', (data) => {
      console.log('CustomAnalytics - Product added to cart:', data);
    });

    // Triggers when an existing cart line decreases in quantity or a cart line is removed
    subscribe('product_removed_from_cart', (data) => {
      console.log('CustomAnalytics - Product removed from cart:', data);
    });

    // Register the CustomAnalytics component as ready
    ready();
  }, []);

  return null;
}

TypeScript

import {
  type PageViewPayload,
  type ProductViewPayload,
  type CollectionViewPayload,
  type CartViewPayload,
  type CartUpdatePayload,
  type CartLineUpdatePayload,
  type SearchViewPayload,
  useAnalytics,
} from '@shopify/hydrogen';
import {useEffect} from 'react';

export function CustomAnalytics() {
  const {subscribe, register} = useAnalytics();
  const {ready} = register('CustomAnalytics'); // unique string identifier

  useEffect(() => {
    // Triggers on every page navigation
    subscribe('page_viewed', (data: PageViewPayload) => {
      console.log('CustomAnalytics - Page viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.ProductView>`
    subscribe('product_viewed', (data: ProductViewPayload) => {
      console.log('CustomAnalytics - Product viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CollectionView>`
    subscribe('collection_viewed', (data: CollectionViewPayload) => {
      console.log('CustomAnalytics - Collection viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CartView>`
    subscribe('cart_viewed', (data: CartViewPayload) => {
      console.log('CustomAnalytics - Cart viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.SearchView>`
    subscribe('search_viewed', (data: SearchViewPayload) => {
      console.log('CustomAnalytics - Search viewed:', data);
    });

    // Triggers on a page that uses `<Analytics.CustomView type="custom_promotion_viewed">`
    subscribe('custom_promotion_viewed', (data: unknown) => {
      console.log('CustomAnalytics - Promotion viewed:', data);
    });

    // Triggers when the cart is updated
    subscribe('cart_updated', (data: CartUpdatePayload) => {
      console.log('CustomAnalytics - Cart updated:', data);
    });

    // Triggers when an existing cart line increases in quantity or a new cart line is added
    subscribe('product_added_to_cart', (data: CartLineUpdatePayload) => {
      console.log('CustomAnalytics - Product added to cart:', data);
    });

    // Triggers when an existing cart line decreases in quantity or a cart line is removed
    subscribe('product_removed_from_cart', (data: CartLineUpdatePayload) => {
      console.log('CustomAnalytics - Product removed from cart:', data);
    });

    // Register the CustomAnalytics component as ready
    ready();
  }, []);

  return null;
}

Was this page helpful?