url()
🧭 API map
| I want to… | Details |
|---|---|
| See every accepted call style | Signatures |
| See common and advanced usage | Usage and behavior |
| Customize messages | Message configuration |
| Understand reactive constraints | Reactive behavior |
| Return to the complete catalog | Built-in validators |
📐 Signatures
url
url(message)
url(options)
This validator has no configurable constraint value. Its options customize the failure message,
which may itself be reactive, and the reactive when condition.
📖 Usage and behavior
Validates an absolute WHATWG URL. It can be passed directly or called with message options:
const myForm = form({
website: field('', [required, url]),
documentationUrl: field('', [
url('Enter a complete URL.'),
]),
});
null and '' pass. The validator uses new URL(value) without a base URL. It accepts absolute URLs with any valid scheme—including https:, mailto:, and custom schemes—but rejects relative references such as /account. A failure is { kind: 'url', message }; the rejected URL is intentionally omitted.
💬 Message configuration
Every failure has a default English message. Where supported, pass a string as the final argument or use an options object for a static or reactive message, as shown above.
A message function may read signals. Returning undefined continues through node, Angular
provider, process-wide, and built-in message fallbacks. See
Validator messages.
⚡ Reactive behavior
The options object accepts a reactive when predicate. Signals read from its validator context are
tracked; while it returns false, the rule contributes neither errors nor constraint metadata.
const requireAbsoluteUrl = signal(false);
const website = field('/account', [
url({ when: () => requireAbsoluteUrl() })
]);
Reactive constraint functions and message functions track the signals they read. When a resolved constraint becomes unavailable, validators that support optional constraint sources temporarily stop contributing their error and metadata.
The validator runs synchronously as part of its node's validator source. Disabled, readonly, and hidden nodes skip validation until they become interactive again.