Hidden Fields

Capture metadata, tracking data, and computed values with invisible fields that resolve dynamically at runtime.

View as Markdown

Hidden Fields

Hidden fields capture contextual data without any visible UI. They use resolvers — declarative configs that compute a value when the form mounts. There are 19 built-in resolvers, all JSON-serializable.

Unlike HTML’s <input type="hidden">, a hidden field renders nothing at all — the value lives only in form state and is included in the submitted data.


When to Use Hidden Fields

Use Case Example Resolver
Track form submission time { $resolver: 'timestamp' }
Capture all UTM parameters { $resolver: 'utm' }
Capture an ad click id { $resolver: 'clickId' }
Record the referring page { $resolver: 'referrer' }
First-touch landing page { $resolver: 'landingPage' }
Visitor’s timezone / device { $resolver: 'timezone' } / deviceType
Read a cookie or storage value { $resolver: 'cookie', name: '_ga' }
Unique id per form load { $resolver: 'submissionId' }

Quick Start

import { FormBuilder } from '@saastro/forms';

const config = FormBuilder.create('contact')
  .addField('email', (f) => f.type('email').label('Email').required())
  // Invisible — resolved at form mount
  .addField('submitted_at', (f) => f.type('hidden').resolver({ $resolver: 'timestamp' }))
  .addField('utm_source', (f) =>
    f.type('hidden').resolver({
      $resolver: 'urlParam',
      param: 'utm_source',
      fallback: 'direct',
    }),
  )
  .addStep('main', ['email', 'submitted_at', 'utm_source'])
  .build();

On submit, the data includes:

{
  "email": "user@example.com",
  "submitted_at": "2026-02-25T12:00:00.000Z",
  "utm_source": "google"
}

Built-in Resolvers

timestamp

Returns the current date/time as an ISO 8601 string.

f.type('hidden').resolver({ $resolver: 'timestamp' });
// → "2026-02-25T12:34:56.789Z"

hostname

Returns window.location.hostname.

f.type('hidden').resolver({ $resolver: 'hostname' });
// → "example.com"

pageUrl

Returns the full page URL (window.location.href).

f.type('hidden').resolver({ $resolver: 'pageUrl' });
// → "https://example.com/contact?ref=nav"

referrer

Returns document.referrer — the URL of the page that linked here.

f.type('hidden').resolver({ $resolver: 'referrer' });
// → "https://www.google.com/search?q=react+form+library"

userAgent

Returns the browser’s user agent string.

f.type('hidden').resolver({ $resolver: 'userAgent' });
// → "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."

urlParam

Reads a query parameter from the current URL.

f.type('hidden').resolver({
  $resolver: 'urlParam',
  param: 'utm_source', // required — param name
  fallback: 'direct', // optional — default if param not found
});
// URL: ?utm_source=google → "google"
// URL: (no param)         → "direct"

ip

Fetches the visitor’s IP address from an external API. This is the only async resolver.

f.type('hidden').resolver({
  $resolver: 'ip',
  endpoint: 'https://ip.example.com/json', // required — there is no default service
  fallback: 'unknown', // optional — used if the fetch fails
});
// → "203.0.113.42"

The endpoint must return JSON with an ip property (e.g. ipify does). Since 0.25 there is no default endpoint: without endpoint no request is made, fallback is returned and a warning is logged once — the visitor’s IP is never sent to a third party you did not pick. The request is capped at 5 seconds — on timeout or any fetch error the resolver returns fallback (or ''), so a down IP service never blocks the form.

Marketing attribution

All synchronous and client-side.

// All `utm_*` query params, as an object: { utm_source, utm_medium, ... }
f.type('hidden').resolver({ $resolver: 'utm' });

// First present ad-click id (gclid, fbclid, msclkid, ttclid, li_fat_id, twclid, dclid).
// `params` overrides the list; `fallback` if none present.
f.type('hidden').resolver({ $resolver: 'clickId', fallback: '' });

// First-touch: the entry URL / referrer of the session, persisted to
// sessionStorage on the first run so later pages keep the original.
// Persisted only with consent (see "Consent and what the library stores" below).
f.type('hidden').resolver({ $resolver: 'landingPage' });
f.type('hidden').resolver({ $resolver: 'firstReferrer' });

@saastro/forms does not know any cookie banner. By default it does nothing on the visitor’s device by itself: until you wire a consent source, the first-touch resolvers keep their value in memory for the life of the page (coherent across the steps of a form, never written anywhere), and the cookie, storage and ip resolvers return their fallback without reading or calling anything.

import { setConsent } from '@saastro/forms';

// Wire your banner once, at startup. `get` is asked on every use; `subscribe` (optional) tells the
// library when the visitor grants or withdraws consent.
setConsent({
  get: (category) => category !== 'necessary' && myBanner.accepted('analytics'),
  subscribe: (onChange) => myBanner.on('change', onChange), // return the unsubscribe function
});

// Or, if your site does not need consent for this, say so on purpose:
setConsent('not-required');
  • Consent is read again when it changes and when the form is submitted. The hidden fields that depend on it (landingPage, firstReferrer, cookie, storage, ip) are resolved again whenever the consent changes (if the provider has subscribe), so the form state never keeps a value obtained with a consent that no longer exists, and once more at submit with the consent the visitor has then (the final word, even if the provider did not notify): granted after the form mounted and before sending, the data goes out; withdrawn in between, it does not (and what the library stored is deleted). submissionId, timestamp and the other values that need no consent keep the value they had when the form mounted.
  • Granting saves the first-touch the page already knew (it is the first touch) the next time one of those fields is resolved.
  • Withdrawing deletes the two keys the library wrote (below) and empties the in-memory copy; anything else in storage is left alone.
  • A provider that throws or returns anything other than true counts as not granted. necessary never asks the provider.
  • Deleting does not depend on subscribe: whenever consent is missing, resolving a first-touch field also removes those two keys, so keys left by an earlier version or by a provider that only has get do not survive.

The API, all exported from @saastro/forms:

Export What it is
setConsent(config) Wires the consent source (a ConsentConfig), or removes it with null.
hasConsent(category) true if the library may act for that ConsentCategory right now. Without wiring it is false.
ConsentCategory The purpose of an access: 'necessary', 'attribution' or 'enrichment'.
ConsentProvider { get(category): boolean; subscribe?(onChange): () => void }: what your banner implements.
ConsentConfig A ConsentProvider, or 'not-required' to declare on purpose that your site needs no consent.

Wiring your banner: @saastro/forms/consent

You can always implement { get, subscribe } yourself. If your banner fits one of these shapes, the optional subpath saves you the code (the core never imports it):

import { setConsent } from '@saastro/forms';
import { fromCookie, fromGoogleConsentMode } from '@saastro/forms/consent';

// A banner that keeps its decision in a JSON cookie and fires an event when it changes.
// `map` says which checkbox grants each purpose (default: `analytics` for both).
setConsent(
  fromCookie({
    name: 'cookie_consent',
    event: 'cookie-consent-updated',
    map: { attribution: 'analytics', enrichment: 'marketing' },
  }),
);

// Or follow Google Consent Mode: it reads the `gtag('consent', …)` calls in `dataLayer`.
setConsent(fromGoogleConsentMode({ map: { enrichment: 'ad_user_data' } })); // default: analytics_storage

A purpose is granted only when its checkbox is exactly true (cookie) or 'granted' (Google). A missing, corrupt or non-object cookie grants nothing. necessary is never asked to the banner.

Google Consent Mode default calls scoped with region: [...] apply only to visitors of those regions, and the library does not know where the visitor is, so it fails closed: a regional default never grants, and one that denies is respected until an update (the visitor’s own decision) changes it.

Type Fields
FromCookieOptions name (the cookie), map? (checkbox that grants attribution / enrichment), event? (event(s) your banner fires on window)
FromGoogleConsentModeOptions map?: Google consent type that grants attribution / enrichment (default analytics_storage)

Data-subject requests

import { clearStoredData, getStoredKeys } from '@saastro/forms';

getStoredKeys({ formIds: ['contact'] }); // what the library has stored right now, and why
clearStoredData({ formIds: ['contact'] }); // delete it (also the in-memory first-touch)
Type Fields
StoredKey area ('session' or 'local'), key, purpose (one sentence for your policy), category
StoredDataOptions formIds?: the forms whose localStorage plugin draft (form-<formId>) should be listed or deleted

Both only touch what the library wrote: its own sessionStorage keys and, for the formIds you list, the draft of the localStorage plugin. They do not ask for consent: looking at or deleting your own data collects nothing.

What each built-in resolver does on the device, and under which purpose:

Resolver Device Category
landingPage, firstReferrer Writes sessionStorage attribution
cookie, storage Reads a cookie / storage key attribution
ip Calls the endpoint you declare enrichment
All the others (timestamp, pageUrl, utm, clickId, urlParam, …) Nothing (page / browser values) necessary

What the library writes to the device:

Key (sessionStorage) Written by Purpose Duration Category
saastro_landing_page landingPage resolver URL the session entered through Session attribution
saastro_first_referrer firstReferrer resolver Referrer of the session’s first page Session attribution

Not governed by setConsent (explicit choices of the site, not defaults of the library): the localStorage plugin (autosave of what the visitor types, only if you register it; it excludes passwords, files and resolved hidden fields) and the reCAPTCHA / Turnstile plugins, which load a third-party script. Reading the current URL, UTM parameters or click ids from the address bar writes nothing. Whether any of this needs consent for your site is a legal judgement for you to make.

Everything the library touches on the device goes through one internal module, and a test fails if any other file starts reading or writing storage or cookies.

Browser & device context

f.type('hidden').resolver({ $resolver: 'language' });          // navigator.language → "es-ES"
f.type('hidden').resolver({ $resolver: 'timezone' });          // IANA → "Europe/Madrid"
f.type('hidden').resolver({ $resolver: 'screenResolution' });  // "1920x1080"
f.type('hidden').resolver({ $resolver: 'deviceType' });        // "mobile" | "tablet" | "desktop"
f.type('hidden').resolver({ $resolver: 'pageTitle' });         // document.title

Storage & generated

// A named cookie (decoded).
f.type('hidden').resolver({ $resolver: 'cookie', name: '_ga', fallback: '' });

// localStorage / sessionStorage by key.
f.type('hidden').resolver({ $resolver: 'storage', key: 'visitor_id', area: 'local', fallback: '' });

// A fresh UUID per form load (idempotency / dedup).
f.type('hidden').resolver({ $resolver: 'submissionId' });

Server-side capture (IP & geo)

Client resolvers run in the browser, so the IP/geo they report can be spoofed and depend on external APIs. When a form is submitted through the hosted Saastro backend (submit.saastro.io, e.g. via HubForm), the server adds trustworthy context to every submission from the Cloudflare edge — no field config needed:

Field Value
client_ip Real connecting IP (CF-Connecting-IP)
geo_country Country code, e.g. ES
geo_city City
geo_region Region / state
geo_postal_code Postal code
geo_timezone IANA timezone
geo_latitude / geo_longitude Approximate coordinates

These are server-authoritative — a client posting a geo_country field can’t override them. They land in the stored submission and flow to integrations (Google Sheets adds a column per field). Capture is on by default; turn it off per form with the Data Capture toggle in the visual builder’s Form Settings (privacy / GDPR). Prefer this over the client ip resolver when you control the backend.


How Resolvers Execute

The useHiddenFieldResolvers hook runs inside the Form component:

  1. On mount, it filters all fields with type: 'hidden'
  2. Runs all resolvers in parallel via Promise.all
  3. Once all resolvers finish, sets each value with react-hook-form’s setValue(name, value, { shouldDirty: false })
  4. A cleanup function prevents stale writes if the component unmounts

Most resolvers are synchronous (timestamp, hostname, etc.). The ip resolver uses fetch and is async. All resolvers execute concurrently regardless.


Resolvers vs Field Mapping Inject

Both resolvers and field mapping inject can add computed values. Use the right tool:

Feature Hidden Field Resolver Field Mapping Inject
When it runs Form mount (once) Before submit action
Visible in form state Yes (via setValue) No (transform only)
Configurable per-field Yes Per submit action
Supports custom resolver No (serializable only) Yes (inject accepts any resolver)

Use resolvers when the value should be part of the form state (available to conditional logic and anything else that reads form values).

Use inject when you only need the value at submit time and it doesn’t need to be in form state.


JSON Configuration

Hidden fields are fully serializable — no functions required:

{
  "fields": {
    "submitted_at": {
      "type": "hidden",
      "resolver": { "$resolver": "timestamp" }
    },
    "utm_source": {
      "type": "hidden",
      "resolver": {
        "$resolver": "urlParam",
        "param": "utm_source",
        "fallback": "direct"
      }
    },
    "visitor_ip": {
      "type": "hidden",
      "resolver": {
        "$resolver": "ip",
        "fallback": "unknown"
      }
    }
  }
}

This makes hidden fields compatible with any visual builder or CMS that stores form config as JSON.


The custom Resolver (Not for Hidden Fields)

The full FieldResolver union has an eighth member, { $resolver: 'custom', fn: () => unknown }, which runs an arbitrary function. Hidden fields exclude it by design: HiddenFieldProps.resolver and FieldBuilder’s .resolver() method are typed SerializableFieldResolver (the union minus custom), so there is no type-supported way to attach a custom resolver to a hidden field — hidden field configs stay fully JSON-serializable.

Where custom is supported at the config level is a submit action’s fieldMapping.inject, which accepts any resolver:

const config = FormBuilder.create('contact')
  .addField('email', (f) => f.type('email').label('Email').required())
  .addStep('main', ['email'])
  .submitAction(
    'crm',
    {
      type: 'http',
      name: 'CRM',
      endpoint: { url: 'https://api.example.com/leads', method: 'POST' },
    },
    'onSubmit',
    {
      fieldMapping: {
        inject: {
          request_id: { $resolver: 'custom', fn: () => crypto.randomUUID() },
        },
      },
    },
  )
  .build();

(The exported resolveValue / applyFieldMapping utilities also execute custom resolvers if you call them directly. A custom resolver that throws is caught: it logs a warning and resolves to '' instead of failing the submit.)

If you need a custom value in form state, use the field-level computed config (reactive, derived from other fields — see useComputedFields) or set the value imperatively via the Form ref’s setValue.


TypeScript Types

All three types are exported from the package:

import type { HiddenFieldProps, FieldResolver, SerializableFieldResolver } from '@saastro/forms';

Their shapes, for reference:

// Full resolver union (includes 'custom')
type FieldResolver =
  | { $resolver: 'timestamp' }
  | { $resolver: 'hostname' }
  | { $resolver: 'pageUrl' }
  | { $resolver: 'referrer' }
  | { $resolver: 'userAgent' }
  | { $resolver: 'urlParam'; param: string; fallback?: string }
  | { $resolver: 'ip'; endpoint?: string; fallback?: string }
  | { $resolver: 'custom'; fn: () => unknown };

// Serializable subset (JSON-safe — what hidden fields require)
type SerializableFieldResolver = Exclude<FieldResolver, { $resolver: 'custom' }>;

// The hidden field config
interface HiddenFieldProps extends BaseFieldProps {
  type: 'hidden';
  resolver: SerializableFieldResolver;
}

API Reference

resolveValue(resolver)

Async function that executes any FieldResolver (including custom) and returns its value.

import { resolveValue } from '@saastro/forms';

const value = await resolveValue({ $resolver: 'timestamp' });
// → "2026-02-25T12:34:56.789Z"

resolveValueSync(resolver)

Synchronous variant — useful for dry-running a config without side effects, e.g. to preview what a form will capture. Returns instant values for synchronous resolvers and placeholder strings for async ones: ip returns its fallback if set, otherwise "[fetching IP...]"; custom returns "[custom resolver]".

import { resolveValueSync } from '@saastro/forms';

const value = resolveValueSync({ $resolver: 'timestamp' });
// → "2026-02-25T12:34:56.789Z"

const ipValue = resolveValueSync({ $resolver: 'ip' });
// → "[fetching IP...]"

useHiddenFieldResolvers(methods, fields)

React hook that resolves all hidden field values on mount. See the useHiddenFieldResolvers reference for details.

import { useHiddenFieldResolvers } from '@saastro/forms';

// Used internally by the Form component — you don't need to call this directly
useHiddenFieldResolvers(formMethods, formConfig.fields);

BUILTIN_RESOLVERS

Constant array with { id, label, description } metadata for all 19 built-in resolvers — useful for building resolver pickers in your own tooling.

import { BUILTIN_RESOLVERS } from '@saastro/forms';

// [
//   { id: 'timestamp', label: 'Timestamp', description: 'Current date/time in ISO format' },
//   { id: 'hostname', label: 'Hostname', description: 'Current page hostname' },
//   ...
// ]