Skip to content

Upgrade: v2.5 to v2.7

This guide takes a project from Velocity 2.5.1 or any 2.6.x release to Velocity 2.7.0. Nothing in your pages has to change. There’s one small API change and a few visible ones, all listed below. Coming from 2.4 or earlier? Follow v2.4 to v2.5.1 first; the upgrade itself goes straight to 2.7.0.

2.62.7
Dialog<div role="dialog">, a script focus trap, overflow: hidden on <body>Native <dialog> with showModal(), data-dialog-open
DropdownAbsolutely positioned, clipped by overflow parentsNative popover in the top layer, anchored to its button
Form errorsOnly when the server rejects a submissionAfter a visitor leaves an invalid field, in the site’s language
Dark modeNative controls and scrollbars stay lightcolor-scheme follows the theme
PrerenderingOpt-in with speculation: 'prerender'
Destructive colourNever appliedApplied, and passes WCAG AA

See the changelog for everything, and Helpers for the new attributes and utilities.

Terminal window
npm create velocity-astro@latest upgrade
  1. dialogElement.open(): if your own code called it, change it to window.openDialog(id) or showModal(). On a <dialog>, open is a built-in boolean property, not a method. close() still works, and window.openDialog / window.closeDialog are unchanged.
  2. Destructive styling now renders. bg-destructive, text-destructive and border-destructive did nothing before 2.7 because the token was never mapped. Destructive buttons and error text now show in red: a deeper red in light mode, and light red with dark text in dark mode.
  3. Custom themes. If you wrote your own theme file instead of using default or midnight, check that --destructive has at least 4.5:1 contrast with --destructive-foreground and with your background. See Destructive.
  4. Forms show errors after interaction. Fields with required, type="email", minlength or maxlength now show a message under them once a visitor leaves them invalid. If your project overrides UI strings for another language, translate the new form.validation.* keys in src/i18n/translations/<locale>.ts. See Errors after interaction.
  5. Dropdown and Carousel markup. Dropdown’s menu is now a popover, and Carousel wraps slides that are links, buttons or images. If you have CSS that targets either component’s internals, check it still applies.

2.7 can make Chromium browsers render a page in the background when a visitor hovers a link to it, so the page opens instantly. It’s off unless you add this to src/config/site.config.ts:

const siteConfig: SiteConfig = {
// ...
speculation: 'prerender',
};

Add speculation?: 'off' | 'prerender'; to the SiteConfig interface in the same file. Upgrades don’t change site.config.ts, so your copy won’t have it yet.

Terminal window
npm install
npm run validate
npm run build && npm run test:e2e