UTM Builder

Builds a tagged campaign URL. Values are lower-cased with underscores for spaces, because analytics tools treat Summer Sale, summer sale and summer_sale as three separate campaigns and nobody reconciles them later.

src/components/ui/utm-builder.tsx

About

From the component's own source, where it was written.

Builds a tagged campaign URL.

Values are lower-cased and spaces become underscores, because analytics tools treat Summer Sale, summer sale and summer_sale as three different campaigns. Cleaning at the point the link is made is the only reliable place — nobody reconciles them afterwards.

Existing query parameters on the base URL are preserved rather than overwritten. Pasting a link that already carries a referral code and having it silently dropped is how attribution disappears.

Encoding is done by URL, not by hand. A campaign name with an ampersand quietly truncates every parameter after it when the string is concatenated.

Install

npx astralyx-ui add utm-builder

Usage

import { UtmBuilder } from '@/components/ui/utm-builder'

<UtmBuilder baseUrl="https://example.com/pricing" onUrlChange={setUrl} />

Composer

Change the props and the source below follows.

Destination URL

utm_source *

utm_medium *

utm_campaign *

utm_term

utm_content

Source, Medium, Campaign needed for attribution to work.

https://example.com/pricing?ref=partner

Props

baseUrl

destinationLabel

tsx

<UtmBuilder baseUrl="https://example.com/pricing" onUrlChange={setUrl} />

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`UtmBuilder`

Extends Omit<ComponentProps<'div'>, 'onChange'>.

Prop	Type	Default	Description
baseUrl	string	—	The destination. Existing query parameters are preserved — a link that already carries a referral code keeps it.
onUrlChange	(url: string) => void	—	Fires when the finished URL is copied.
destinationLabel	ReactNode	'Destination URL'	—
destinationPlaceholder	string	'https://example.com/pricing'	—

Functions

Function	Signature	Description
normaliseUtm	(value: string) => string	Lower-case, underscores for spaces — three spellings become one campaign.

Behaviour

Topic	Detail	Description
normalisation	automatic	Lower-cased, spaces to underscores. Cleaning at the point the link is made is the only place it reliably happens.
encoding	via URL	Built with `URL`, not string concatenation. A campaign name containing an ampersand would silently truncate every parameter after it.