UTM Params

Read and persist UTM parameters from the URL (utm_source, utm_id, utm_s1) into cookies, and optionally map extra URL params to custom cookie names. Values are available as subid1, subid2, subid3 and extra.

Installation

tsx

import { useUtmParams } from "@workspace/lp-core"

Basic usage

Call the hook (client-only). With no options, it uses default cookie names and 30-day persistence. URL is stripped of UTM params after reading so they are not visible in the address bar.

tsx

const { subid1, subid2, subid3 } = useUtmParams()

// subid1 = utm_source, subid2 = utm_id, subid3 = utm_s1
// Values come from URL first, then from cookies

Extra UTM mappings

Pass extra to read additional URL params and store them in named cookies. Result includes an extra object keyed by cookie name.

tsx

const { subid1, subid2, subid3, extra } = useUtmParams({
  cookieDays: 30,
  extra: [
    { urlParam: "utm_campaign", cookieName: "subid4" },
    { urlParam: "utm_medium", cookieName: "subid5" },
  ],
})

// extra.subid4, extra.subid5

Current values (this page):

subid1: (empty)

subid2: (empty)

subid3: (empty)

subid4: (empty)

subid5: (empty)

URL param keys

Default mapping: utm_source → subid1, utm_id → subid2, utm_s1 → subid3. Cookie names are subid1, subid2, subid3.

Options (useUtmParams argument)

Prop	Type	Default	Description
cookieDays	number	30	Days to persist UTM values in cookies.
extra	UtmParamMapping[]	-	Additional URL param to cookie mappings. Each has urlParam and cookieName.

Return value

Prop	Type	Default	Description
subid1	string	-	Value from utm_source (URL or cookie).
subid2	string	-	Value from utm_id (URL or cookie).
subid3	string	-	Value from utm_s1 (URL or cookie).
extra	Record<string, string>	-	Present when options.extra is provided; keys are cookie names.