url field

A url() field stores absolute URLs as strings. It validates that the input starts with a URL scheme (http:// or https://) and renders the value as a clickable link in the admin data table. Common uses include website links, canonical URLs, external resource references, and social profile URLs.

Config options

| Option | Type | Default | Description | |--------|------|---------|-------------| | label | string | "" | Display label in the admin panel. Inferred from the field key by defineCollection when left empty. | | required | boolean | false | When false, the field is wrapped in v.optional(…) in the schema. | | defaultValue | string | — | Pre-filled value shown in the admin form when creating a new document. | | min | number \| [number, string] | — | Minimum character length constraint. Bare number, or a [value, customError] tuple for a custom error message. | | max | number \| [number, string] | — | Maximum character length constraint. Bare number, or a [value, customError] tuple. | | index | string \| { name, additionalFields?, draftStatus? } | — | Convex index name, or the object form for a compound index. | | description | string | — | Helper text shown below the field input. | | admin.hidden | boolean | false | Hides the field from the admin edit form entirely. | | admin.readOnly | boolean | false | Renders the input as non-interactive. | | admin.position | "main" \| "sidebar" | "main" | Column in the admin edit layout where this field appears. | | admin.width | string | "100%" | CSS width of the field in the edit form (e.g. "50%", "240px"). Meaningful as a child of row(); below a narrow form column every field renders full width regardless. | | admin.cellAlignment | "left" \| "center" \| "right" | "left" | Horizontal alignment of the value in the list-view table cell. | | admin.placeholder | string | — | Placeholder text shown when the input is empty. | | admin.description | string | — | Helper text displayed below the field input. | | admin.condition | (props: { data, siblingData }) => boolean | — | Shows the field only while this returns true. A throwing condition counts as met. Hidden fields skip required/validate on the server too. See the Conditional fields & masks guide. | | admin.mask | string \| string[] \| { mask, storeMasked?, options? } \| false | — | An opt-in use-mask-input pattern, or false to opt out of a project-wide default set via fields.inputMasks.url. See the Conditional fields & masks guide. |

Schema output

// Optional (required: false — default)
website: v.optional(v.string())

// Required with a length cap and database index
website: v.string(),
.index("by_website", ["website"])

Usage

import { defineCollection, url, text } from "@vexcms/core";

const pages = defineCollection({
  slug: "pages",
  fields: {
    // Minimal — label inferred from key ("Canonical Url")
    canonicalUrl: url(),

    // Required website URL with a length cap and database index
    website: url({ required: true, max: 2048, index: "by_website" }),

    // Social profile URL with a placeholder hint
    twitterUrl: url({
      required: false,
      admin: { width: "50%", placeholder: "https://twitter.com/username" },
    }),

    // Pre-filled default
    homepageUrl: url({ defaultValue: "https://example.com" }),
  },
});

Admin UI

The URL field renders as a single-line <input type="url"> in the edit form. The browser validates that the value is a well-formed URL. In the list-view table, the value is rendered as a clickable <a> link that opens in a new tab. URL fields are commonly placed in the sidebar (e.g. social links) or used as half-width fields alongside text fields.