API reference

Functions

GoogleAnalytics()

function GoogleAnalytics(props): Element;

Initializes GA4 on the client and sends page views on pathname changes.

Mount once inside a TanStack Router root. Search/hash-only changes do not trigger page views. The component renders nothing during SSR and reuses an existing gtag loader script.

Parameters

Parameter	Type	Description
`props`	`GoogleAnalyticsProps`	See GoogleAnalyticsProps. `deferred` defaults to `true`.

Returns

Element

A client-only element that renders nothing visible.

Example

<GoogleAnalytics measurementId="G-XXXXXXXXXX" deferred={false} />

useGoogleAnalytics()

function useGoogleAnalytics(): object;

Returns stable helpers for gtag commands: set, config, event, consent, and get.

The returned object is memoized for the lifetime of the component, so it is safe in effect dependency arrays.

Commands are safe to call during SSR (they do nothing without a browser). Browser calls create the gtag queue if needed; mount GoogleAnalytics to load the GA script. The get callback requires a working GA script and may never run if loading is blocked.

Returns

An object with the set, config, event, consent, and get commands.

Name	Type	Description
`set()`	(`params`) => `void`	Sets shared parameters for subsequent events.
`config()`	(`measurementId`, `configParams?`) => `void`	Configures a stream. Set `send_page_view` to `false` to avoid an extra automatic page view.
`event`	`GoogleAnalyticsCommandEvent`	Sends a recommended or custom event with optional parameters. Param eventName A recommended event name or any custom event name. Param params Event parameters; required for recommended events that need them.
`consent()`	(`mode`, `params`) => `void`	Queues consent defaults or an update from your own consent interface.
`get()`	(`measurementId`, `fieldName`, `callback`) => `void`	Requests a field asynchronously; the callback is invoked by the loaded GA script.

Example

const { event } = useGoogleAnalytics();
event('sign_up', { method: 'email' });
event('editor_opened', { tool: 'brush' });

Type Aliases

GoogleAnalyticsProps

type GoogleAnalyticsProps = object;

Options for the client-only GA4 component. Keep config objects stable across renders.

Properties

config?

config?: GoogleAnalyticsConfig;

Stream configuration. Automatic gtag page views are always disabled by this component.

consentDefaults?

consentDefaults?: GoogleAnalyticsConsentParams;

Initial consent commands, queued before stream configuration. Does not block script loading.

measurementId

measurementId: string;

GA4 web stream measurement ID, such as G-XXXXXXXXXX.

deferred?

deferred?: boolean;

Wait for requestIdleCallback when available. Defaults to true; no idle timeout is set.

GoogleAnalyticsCommandEvent

type GoogleAnalyticsCommandEvent = {
  <TEventName>(eventName, params): void;
  (eventName, params?): void;
};

Signature of the event command: typed parameters for recommended events, plus an open overload for custom events.

Call Signature

<TEventName>(eventName, params): void;

Type Parameters

Type Parameter
`TEventName` extends keyof `GoogleAnalyticsRecommendedEventParamsMap`

Parameters

Parameter	Type
`eventName`	`TEventName`
`params`	`GoogleAnalyticsRecommendedEventParamsMap`[`TEventName`]

Returns

void

Call Signature

(eventName, params?): void;

Parameters

Parameter	Type
`eventName`	`string`
`params?`	`GoogleAnalyticsEventParams`

Returns

void

Example

event('sign_up', { method: 'email' });
event('editor_opened', { tool: 'brush' });

GoogleAnalyticsPrimitive

type GoogleAnalyticsPrimitive = string | number | boolean | null;

A scalar value accepted in GA4 parameters and user properties.

GoogleAnalyticsParameterValue

type GoogleAnalyticsParameterValue = 
  | GoogleAnalyticsPrimitive
  | GoogleAnalyticsParameterValue[]
  | {
[key: string]: GoogleAnalyticsParameterValue;
};

A JSON-like value for an event or set parameter: a primitive, an array, or a nested object.

GoogleAnalyticsEventParams

type GoogleAnalyticsEventParams = Record<string, 
  | GoogleAnalyticsParameterValue
| undefined>;

Parameters for an event, keyed by parameter name. Undefined values are allowed and omitted by gtag.

GoogleAnalyticsConfig

type GoogleAnalyticsConfig = object;

Stream configuration passed to the gtag config command.

Field names match the gtag.js configuration parameters.

See

https://developers.google.com/analytics/devguides/collection/ga4/reference/config

Properties

allow_ad_personalization_signals?

allow_ad_personalization_signals?: boolean;

Set to false to disable advertising personalization signals for this stream.

allow_google_signals?

allow_google_signals?: boolean;

Set to false to disable Google signals (cross-device and demographic data) for this stream.

campaign_content?

campaign_content?: string;

Campaign content (utm_content) to attribute traffic to, overriding the URL value.

campaign_id?

campaign_id?: string;

Campaign ID (utm_id) to attribute traffic to, overriding the URL value.

campaign_medium?

campaign_medium?: string;

Campaign medium (utm_medium) to attribute traffic to, overriding the URL value.

campaign_name?

campaign_name?: string;

Campaign name (utm_campaign) to attribute traffic to, overriding the URL value.

campaign_source?

campaign_source?: string;

Campaign source (utm_source) to attribute traffic to, overriding the URL value.

campaign_term?

campaign_term?: string;

Campaign term (utm_term) to attribute traffic to, overriding the URL value.

client_id?

client_id?: string;

Overrides the client ID that identifies this browser, instead of the one gtag generates.

content_group?

content_group?: string;

Content group to assign to page views, for grouping pages in reports.

cookie_domain?

cookie_domain?: string;

Domain for the GA cookies. Defaults to automatic domain detection.

cookie_expires?

cookie_expires?: number;

Lifetime of the GA cookies, in seconds.

cookie_flags?

cookie_flags?: string;

Extra attributes appended to the GA cookies, such as SameSite=None;Secure.

cookie_path?

cookie_path?: string;

Path for the GA cookies.

cookie_prefix?

cookie_prefix?: string;

Prefix added to the GA cookie names.

cookie_update?

cookie_update?: boolean;

Whether gtag refreshes the cookie expiration on each page load.

debug_mode?

debug_mode?: boolean;

Set to true to send events to the GA4 DebugView.

ignore_referrer?

ignore_referrer?: boolean;

Set to true to ignore the document referrer when attributing traffic.

language?

language?: string;

Browser language, such as en-us.

page_location?

page_location?: string;

Full URL of the page. Defaults to the current location.

page_path?

page_path?: string;

Path portion of the page URL.

page_referrer?

page_referrer?: string;

URL of the referring page.

page_title?

page_title?: string;

Title of the page.

screen_resolution?

screen_resolution?: string;

Screen resolution in <width>x<height> form, such as 1920x1080.

send_page_view?

send_page_view?: boolean;

Whether gtag sends an automatic page view on configuration. GoogleAnalytics always sets this to false and sends its own page views.

user_id?

user_id?: string;

Your own opaque identifier for the signed-in user, used to associate sessions across devices.

user_properties?

user_properties?: Record<string, GoogleAnalyticsPrimitive>;

Custom user-scoped properties, keyed by property name.

GoogleAnalyticsSetParams

type GoogleAnalyticsSetParams = Record<string, 
  | GoogleAnalyticsParameterValue
| undefined>;

Parameters for the gtag set command, applied to subsequent events.

GoogleAnalyticsConsentState

type GoogleAnalyticsConsentState = "granted" | "denied";

A consent decision for one consent type.

GoogleAnalyticsConsentMode

type GoogleAnalyticsConsentMode = "default" | "update";

Whether a consent command sets the initial default state or an update after the user decides.

GoogleAnalyticsConsentParams

type GoogleAnalyticsConsentParams = object;

Consent Mode states for the gtag consent command. Omitted types keep their current state.

Properties

ad_personalization?

ad_personalization?: GoogleAnalyticsConsentState;

Consent for personalized advertising.

ad_storage?

ad_storage?: GoogleAnalyticsConsentState;

Consent to store advertising-related data, such as cookies.

ad_user_data?

ad_user_data?: GoogleAnalyticsConsentState;

Consent to send user data to Google for advertising.

analytics_storage?

analytics_storage?: GoogleAnalyticsConsentState;

Consent to store analytics data, such as cookies.

wait_for_update?

wait_for_update?: number;

Milliseconds gtag waits for a consent update before sending queued data.

GoogleAnalyticsGettableFieldName

type GoogleAnalyticsGettableFieldName = "campaign_name" | "client_id" | "gclid" | "session_id";

Field names that the gtag get command can read.

GoogleAnalyticsRecommendedEventParamsMap

type GoogleAnalyticsRecommendedEventParamsMap = object;

Maps each recommended event name to the parameters its typed overload of event accepts.

Properties

exception

exception: object;

An error or crash. Carries an optional description and fatal flag.

description?

description?: string;

Short description of the error.

fatal?

fatal?: boolean;

Whether the error was fatal to the app.

generate_lead

generate_lead: GoogleAnalyticsEventParams;

A lead was generated, for example a submitted contact form. Accepts any custom parameters.

login: object;

A user signed in.

method?

method?: string;

How the user authenticated, such as email or google.

page_view

page_view: object;

A page was viewed. GoogleAnalytics sends this on each pathname change.

page_location

page_location: string;

Full URL of the page.

page_path

page_path: string;

Path portion of the page URL.

page_referrer?

page_referrer?: string;

URL of the referring page.

page_title?

page_title?: string;

Title of the page.

send_to?

send_to?: string;

Measurement ID to send this page view to, instead of all configured streams.

search

search: object;

A user searched your content.

search_term

search_term: string;

The text the user searched for.

select_content

select_content: object;

A user selected a piece of content.

content_type

content_type: string;

Type of the selected content, such as product.

item_id?

item_id?: string;

Identifier of the selected content.

share: object;

A user shared content.

content_type?

content_type?: string;

Type of the shared content, such as article.

item_id?

item_id?: string;

Identifier of the shared content.

method

method: string;

How the content was shared, such as email or twitter.

sign_up

sign_up: object;

A user registered for an account.

method?

method?: string;

How the user authenticated, such as email or google.

GoogleAnalyticsRecommendedEventName

type GoogleAnalyticsRecommendedEventName = keyof GoogleAnalyticsRecommendedEventParamsMap;

Names of the recommended events that have typed parameters.

Functions​

GoogleAnalytics()​

Parameters​

Returns​

Example​

useGoogleAnalytics()​

Returns​

Example​

Type Aliases​

GoogleAnalyticsProps​

Properties​

config?​

consentDefaults?​

measurementId​

deferred?​

GoogleAnalyticsCommandEvent​

Call Signature​

Type Parameters​

Parameters​

Returns​

Call Signature​

Parameters​

Returns​

Example​

GoogleAnalyticsPrimitive​

GoogleAnalyticsParameterValue​

GoogleAnalyticsEventParams​

GoogleAnalyticsConfig​

See​

Properties​

allow_ad_personalization_signals?​

allow_google_signals?​

campaign_content?​

campaign_id?​

campaign_medium?​

campaign_name?​

campaign_source?​

campaign_term?​

client_id?​

content_group?​

cookie_domain?​

cookie_expires?​

cookie_flags?​

cookie_path?​

cookie_prefix?​

cookie_update?​

debug_mode?​

ignore_referrer?​

language?​

page_location?​

page_path?​

page_referrer?​

page_title?​

screen_resolution?​

send_page_view?​

user_id?​

user_properties?​

GoogleAnalyticsSetParams​

GoogleAnalyticsConsentState​

GoogleAnalyticsConsentMode​

GoogleAnalyticsConsentParams​

Properties​

ad_personalization?​

ad_storage?​

ad_user_data?​

analytics_storage?​

wait_for_update?​

GoogleAnalyticsGettableFieldName​

GoogleAnalyticsRecommendedEventParamsMap​

Properties​

exception​

description?​

fatal?​

generate_lead​

login​

method?​

page_view​

page_location​

page_path​

page_referrer?​

Functions

GoogleAnalytics()

Parameters

Returns

Example

useGoogleAnalytics()

Returns

Example

Type Aliases

GoogleAnalyticsProps

Properties

config?

consentDefaults?

measurementId

deferred?

GoogleAnalyticsCommandEvent

Call Signature

Type Parameters

Parameters

Returns

Call Signature

Parameters

Returns

Example

GoogleAnalyticsPrimitive

GoogleAnalyticsParameterValue

GoogleAnalyticsEventParams

GoogleAnalyticsConfig

See

Properties

allow_ad_personalization_signals?

allow_google_signals?

campaign_content?

campaign_id?

campaign_medium?

campaign_name?

campaign_source?

campaign_term?

client_id?

content_group?

cookie_domain?

cookie_expires?

cookie_flags?

cookie_path?

cookie_prefix?

cookie_update?

debug_mode?

ignore_referrer?

language?

page_location?

page_path?

page_referrer?

page_title?

screen_resolution?

send_page_view?

user_id?

user_properties?

GoogleAnalyticsSetParams

GoogleAnalyticsConsentState

GoogleAnalyticsConsentMode

GoogleAnalyticsConsentParams

Properties

ad_personalization?

ad_storage?

ad_user_data?

analytics_storage?

wait_for_update?

GoogleAnalyticsGettableFieldName

GoogleAnalyticsRecommendedEventParamsMap

Properties

exception

description?

fatal?

generate_lead

login

method?

page_view

page_location

page_path

page_referrer?