React setup

Install SWAN

Configuring the .npmrc file for your project

SWAN is hosted in a private npm repository. To install the package, you need to ensure your project’s .npmrc file is correctly configured.

For detailed steps on configuring your npm client, see Install NPM Packages from Vistaprint Artifactory.

Install the latest version of SWAN

npm i @vp/swan@latest

npm i @vp/swan@latest

Peer Dependency

react:>=17 <20 (Preferred version ^19)
react-dom:>=17 <20 (Preferred version ^19)

For Library Owners

Add @vp/swan as a dev dependency to help with building, developing, and testing your library. And also declare it as a peer dependency in package.json. This means that any project using your library needs to have @vp/swan installed. Your library will automatically use the version of @vp/swan that the consuming project has, so everything works together smoothly.

{
  "peerDependencies": {
    "@vp/swan": ">=3 <4"
  }
}

{
  "peerDependencies": {
    "@vp/swan": ">=3 <4"
  }
}

This peer dependency range (>=3 <4) ensures your library will stay compatible with all Swan v3.x releases while avoiding breaking changes from v4

Project setup

Choose the setup tab that matches your React project.

Getting Started With SWAN in UBIK

Fortunately, UBIK handles a lot of the scaffolding for the SWAN setup. If you generate a new UBIK fragment using @vp/init you can see an example of a component with SWAN support built in. Please see these docs for more information on UBIK fragments.

Important notes:

You do not need SwanProvider or SwanHead when working with UBIK fragments as this is done for you.
Set required style keys by passing a list to the useSwanStyleKeys hook provided by @vp/ubik-context. An example of how to do this is included in the component generated by @vp/init (shown below), so you can use that as a reference.
- You can add style keys at the component level (scattered throughout your fragment) or you can add all required across a fragment in a single place at the root.
- Note that this only works server side so won't add styles in the browser and we recommend doing this server side where possible.
In a UBIK world, the HTML <body> element doesn’t get the root class name, the root element does. This means that portals that get rendered against <body> don’t receive the styling. When using a portal, the SWAN component should be wrapped in a <Box> applying getRootClassNames(). See the example below.

ComponentExample.tsxPortaledAlertBox.tsx

import { Card, FlexBox, Typography } from '@vp/swan'
import { useLogger, useSwanStyleKeys, useUserContext } from '@vp/ubik-context'
import { Title } from './title'

export interface Props {
  greeting: string
}

export const Component = (props: Props) => {
  const logger = useLogger()
  const userContext = useUserContext()
  logger.log('Rendering fragment for a locale', userContext.locale)

  useSwanStyleKeys(['core'])

  return (
    <FlexBox>
      <Card style={{ width: '100%' }}>
        <Title title="My Title" />
        <Typography textAllCaps fontWeight="bold" mb={1} mr={1}>
          {props.greeting}
        </Typography>
      </Card>
    </FlexBox>
  )
}

import { Card, FlexBox, Typography } from '@vp/swan'
import { useLogger, useSwanStyleKeys, useUserContext } from '@vp/ubik-context'
import { Title } from './title'

export interface Props {
  greeting: string
}

export const Component = (props: Props) => {
  const logger = useLogger()
  const userContext = useUserContext()
  logger.log('Rendering fragment for a locale', userContext.locale)

  useSwanStyleKeys(['core'])

  return (
    <FlexBox>
      <Card style={{ width: '100%' }}>
        <Title title="My Title" />
        <Typography textAllCaps fontWeight="bold" mb={1} mr={1}>
          {props.greeting}
        </Typography>
      </Card>
    </FlexBox>
  )
}

import { AlertBox, Box, getRootClassNames } from '@vp/swan'

export const PortaledAlertBox = () => {
  return (
    <Box className={getRootClassNames()}>
      <AlertBox>Alert in a portal!</AlertBox>
    </Box>
  )
}

import { AlertBox, Box, getRootClassNames } from '@vp/swan'

export const PortaledAlertBox = () => {
  return (
    <Box className={getRootClassNames()}>
      <AlertBox>Alert in a portal!</AlertBox>
    </Box>
  )
}

Getting Started With Vite

SwanConfiguration → Sets up locale, providers, global link config, and injects styles content.
main.tsx → Wrap the entire app inside SwanConfiguration, making sure every page and component has access to global styles and provider.
App.tsx → Defines the page layout using Page Wrappers. To set up a consistent page structure and accessibility patterns (e.g., skip links).

main.tsxSwanConfiguration.tsxApp.tsx

import { createRoot } from 'react-dom/client'
import { SwanConfiguration } from './SwanConfiguration'
import { App } from './App'

const container = document.getElementById('root')
const root = createRoot(container)
root.render(
  <SwanConfiguration>
    <App />
  </SwanConfiguration>,
)

import { createRoot } from 'react-dom/client'
import { SwanConfiguration } from './SwanConfiguration'
import { App } from './App'

const container = document.getElementById('root')
const root = createRoot(container)
root.render(
  <SwanConfiguration>
    <App />
  </SwanConfiguration>,
)

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_STYLE_KEY_MAP,
} from '@vp/swan'
import React from 'react'

const styleKeys = [SWAN_STYLE_KEY_MAP.alertBox, SWAN_STYLE_KEY_MAP.button]

export const SwanConfiguration = ({
  children,
}: {
  children: React.ReactNode
}) => {
  const { tenant, locale } = getTenantAndLocale() // illustration function, actual implementation will vary
  const rootClassName = getRootClassNames()
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      <SwanHead styleSheetKeys={styleKeys} />
      <div className={rootClassName}>
        {/* Optionally, if you need, wrap ScreenProvider at this level */}
        {children}
      </div>
    </SwanProvider>
  )
}

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_STYLE_KEY_MAP,
} from '@vp/swan'
import React from 'react'

const styleKeys = [SWAN_STYLE_KEY_MAP.alertBox, SWAN_STYLE_KEY_MAP.button]

export const SwanConfiguration = ({
  children,
}: {
  children: React.ReactNode
}) => {
  const { tenant, locale } = getTenantAndLocale() // illustration function, actual implementation will vary
  const rootClassName = getRootClassNames()
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      <SwanHead styleSheetKeys={styleKeys} />
      <div className={rootClassName}>
        {/* Optionally, if you need, wrap ScreenProvider at this level */}
        {children}
      </div>
    </SwanProvider>
  )
}

import {
  SiteMain,
  SiteContent,
  SkipLink,
  MainContentStart,
  BoundedContent,
} from '@vp/swan'
import React from 'react'

export const App = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
    </SiteContent>
  )
}

import {
  SiteMain,
  SiteContent,
  SkipLink,
  MainContentStart,
  BoundedContent,
} from '@vp/swan'
import React from 'react'

export const App = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
    </SiteContent>
  )
}

Getting Started With NextJS (with app router)

NextJS's App Router introduces a framework for building applications and relies on React features such as React Server Components (RSCs). The App Router Uses React canary releases built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks, prior to a new React release.

As of SWAN 3.0, all components are marked with 'use client' - meaning they will render on the server, but also hydrate on the client.

SWAN Utility Components and CSS Classes

Because SWAN components are treated as client components, they cannot be used inside of server components (except when passed through as children props).

Instead of rendering something like <P marginTop={3}>My Paragraph</P> the CSS utility classes can be used instead: <p className="swan-mt-3">My Paragraph</p>. This approach lacks type safety, so is best avoided, if possible

app/layout.tsx → This is the single place where you wire up SWAN in a Next.js app.

Wrap the application with SwanProvider to configure the locale, set up the global link component
Apply root-level class names.
Add SwanHead to handle style injection.
Use Page Wrappers to set up a consistent page structure and accessibility patterns.

import {
  SwanHead,
  SwanProvider,
  SWAN_STYLE_KEY_MAP,
  SiteContent,
  SkipLink,
  SiteMain,
  MainContentStart,
  BoundedContent,
  getRootClassNames,
} from '@vp/swan'

const styleKeys = [SWAN_STYLE_KEY_MAP.alertBox, SWAN_STYLE_KEY_MAP.button]

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <html lang={locale}>
      <head>
        <SwanHead
          swanTenant={tenant}
          swanLocale={locale}
          styleSheetKeys={styleKeys}
        />
      </head>
      <body className={rootClassName}>
        <SwanProvider swanTenant={tenant} swanLocale={locale}>
          {/* Optionally, if you need, wrap ScreenProvider at this level */}
          <SiteContent>
            <SkipLink>Skip to main content</SkipLink>
            <SiteMain>
              <MainContentStart />
              <BoundedContent>{children}</BoundedContent>
            </SiteMain>
          </SiteContent>
        </SwanProvider>
      </body>
    </html>
  )
}

import {
  SwanHead,
  SwanProvider,
  SWAN_STYLE_KEY_MAP,
  SiteContent,
  SkipLink,
  SiteMain,
  MainContentStart,
  BoundedContent,
  getRootClassNames,
} from '@vp/swan'

const styleKeys = [SWAN_STYLE_KEY_MAP.alertBox, SWAN_STYLE_KEY_MAP.button]

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <html lang={locale}>
      <head>
        <SwanHead
          swanTenant={tenant}
          swanLocale={locale}
          styleSheetKeys={styleKeys}
        />
      </head>
      <body className={rootClassName}>
        <SwanProvider swanTenant={tenant} swanLocale={locale}>
          {/* Optionally, if you need, wrap ScreenProvider at this level */}
          <SiteContent>
            <SkipLink>Skip to main content</SkipLink>
            <SiteMain>
              <MainContentStart />
              <BoundedContent>{children}</BoundedContent>
            </SiteMain>
          </SiteContent>
        </SwanProvider>
      </body>
    </html>
  )
}

Getting Started With NextJS (with page router)

pages/_app.tsx → Wrap your app with SwanProvider to set up the locale and global link config.
pages/_document.tsx → Lets you customize the <html> and <body> tags. This is where you typically inject SwanHead for stylesheet keys and set the root class names.
layout.tsx → Defines the page layout using Page Wrappers. To set up a consistent page structure and accessibility patterns (e.g., skip links).

pages/_app.tsxpages/_document.tsxLayout.tsx

import { SwanProvider } from '@vp/swan'
import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      <Component {...pageProps} />
    </SwanProvider>
  )
}

import { SwanProvider } from '@vp/swan'
import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      <Component {...pageProps} />
    </SwanProvider>
  )
}

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_STYLE_KEY_MAP,
} from '@vp/swan'
import { Head, Html, Main, NextScript } from 'next/document'
import Link from 'next/link'

const styleKeys = [
  SWAN_STYLE_KEY_MAP.accordion,
  SWAN_STYLE_KEY_MAP.tabs,
  SWAN_STYLE_KEY_MAP.alertBox,
  SWAN_STYLE_KEY_MAP.button,
]
export default function Document() {
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will vary.
  return (
    <Html lang={locale}>
      <Head>
        <SwanHead
          swanTenant={tenant}
          swanLocale={locale}
          styleSheetKeys={styleKeys}
        />
      </Head>
      <body className={rootClassName}>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_STYLE_KEY_MAP,
} from '@vp/swan'
import { Head, Html, Main, NextScript } from 'next/document'
import Link from 'next/link'

const styleKeys = [
  SWAN_STYLE_KEY_MAP.accordion,
  SWAN_STYLE_KEY_MAP.tabs,
  SWAN_STYLE_KEY_MAP.alertBox,
  SWAN_STYLE_KEY_MAP.button,
]
export default function Document() {
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will vary.
  return (
    <Html lang={locale}>
      <Head>
        <SwanHead
          swanTenant={tenant}
          swanLocale={locale}
          styleSheetKeys={styleKeys}
        />
      </Head>
      <body className={rootClassName}>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

import {
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
  SkipLink,
} from '@vp/swan'
import React from 'react'
import Head from 'next/head'

type LayoutProps = {
  pageTitle: string
  pageDescription: string
}

export const Layout: LayoutProps = ({
  children,
  pageTitle,
  pageDescription,
}) => {
  return (
    <>
      <Head>
        <title>{pageTitle}</title>
        <meta name="description" content={pageDescription} />
      </Head>
      <SiteContent>
        <SkipLink>Skip to main content</SkipLink>
        <SiteMain>
          <MainContentStart />
          <BoundedContent>{children}</BoundedContent>
        </SiteMain>
      </SiteContent>
    </>
  )
}

import {
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
  SkipLink,
} from '@vp/swan'
import React from 'react'
import Head from 'next/head'

type LayoutProps = {
  pageTitle: string
  pageDescription: string
}

export const Layout: LayoutProps = ({
  children,
  pageTitle,
  pageDescription,
}) => {
  return (
    <>
      <Head>
        <title>{pageTitle}</title>
        <meta name="description" content={pageDescription} />
      </Head>
      <SiteContent>
        <SkipLink>Skip to main content</SkipLink>
        <SiteMain>
          <MainContentStart />
          <BoundedContent>{children}</BoundedContent>
        </SiteMain>
      </SiteContent>
    </>
  )
}

Gatsby React 19 Support Notice

Gatsby does not yet have official support for React 19. Although work is in progress, no stable release is available at this time.

If you are starting a new project, be cautious when choosing Gatsby, features may not work as expected with React 19. Until official support is released, it’s safer to consider frameworks that already support React 19.

Getting Started With Gatsby

The latest version of Gatsby comes with its own Head management toolkit.

In Summary, all the pages and templates should return a named component called Head which should modify everything in Head. This will receive the data and pageContext that the default component receives.

Additionally, to modify attributes on html or body tag, you need to use the appropriate methods inside onRenderBody (as shown below). Additionally, you could modify head within this as well which are common to all the pages.

Since this doesn't need helmet, you don't need to install helmet, or configure gatsby-config with react-helmet plugin.

Please refer to PageOrTemplate example on how to manage SEO

When using SSR or SSG with React 17, wrap your application in <SwanSSRProvider /> to avoid hydration issues. This step is not needed for React 18 and above.

SwanConfigurationgatsby-browser.tsxgatsby-ssr.tsxPageOrTemplate.tsx

import React from 'react'
import { Helmet } from 'react-helmet'
import { Link } from 'gatsby'
import { SwanProvider, SwanSSRProvider } from '@vp/swan'

export const SwanConfiguration = ({ children }) => {
  const { tenant, locale } = getTenantAndLocale() // illustration function, actual implementation will vary
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      {/* When rendering with CSR, please remove the <SwanSSRProvider /> wrapper */}
      <SwanSSRProvider>
        {/* Optionally, if you need, wrap ScreenProvider at this level */}
        {children}
      </SwanSSRProvider>
    </SwanProvider>
  )
}

import React from 'react'
import { Helmet } from 'react-helmet'
import { Link } from 'gatsby'
import { SwanProvider, SwanSSRProvider } from '@vp/swan'

export const SwanConfiguration = ({ children }) => {
  const { tenant, locale } = getTenantAndLocale() // illustration function, actual implementation will vary
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      {/* When rendering with CSR, please remove the <SwanSSRProvider /> wrapper */}
      <SwanSSRProvider>
        {/* Optionally, if you need, wrap ScreenProvider at this level */}
        {children}
      </SwanSSRProvider>
    </SwanProvider>
  )
}

import { GatsbyBrowser } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbyBrowser['wrapRootElement'] = ({
  element,
}) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbyBrowser } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbyBrowser['wrapRootElement'] = ({
  element,
}) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbySSR } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'
import { SwanHead, SWAN_STYLE_KEY_MAP, getRootClassNames } from '@vp/swan'

const styleKeysToLoad = [SWAN_STYLE_KEY_MAP.button, SWAN_STYLE_KEY_MAP.icon]

export const onRenderBody: GatsbySSR['onRenderBody'] = ({
  setBodyAttributes,
  setHtmlAttributes,
  setHeadComponents,
  pathname,
}) => {
  const bodyClassNames = getRootClassNames()
  const { locale, tenant } = getLocaleAndTenant() // Illustration function. Actual implementatoin will vary
  setHtmlAttributes({
    lang: locale,
  })
  setHeadComponents([
    <SwanHead
      key="swan-head"
      swanTenant={tenant}
      swanLocale={locale}
      styleSheetKeys={styleKeysToLoad}
    />,
  ])

  setBodyAttributes({
    className: bodyClassNames,
  })
}

export const wrapRootElement: GatsbySSR['wrapRootElement'] = ({ element }) => (
  <SwanConfiguration>{element}</SwanConfiguration>
)

import { GatsbySSR } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'
import { SwanHead, SWAN_STYLE_KEY_MAP, getRootClassNames } from '@vp/swan'

const styleKeysToLoad = [SWAN_STYLE_KEY_MAP.button, SWAN_STYLE_KEY_MAP.icon]

export const onRenderBody: GatsbySSR['onRenderBody'] = ({
  setBodyAttributes,
  setHtmlAttributes,
  setHeadComponents,
  pathname,
}) => {
  const bodyClassNames = getRootClassNames()
  const { locale, tenant } = getLocaleAndTenant() // Illustration function. Actual implementatoin will vary
  setHtmlAttributes({
    lang: locale,
  })
  setHeadComponents([
    <SwanHead
      key="swan-head"
      swanTenant={tenant}
      swanLocale={locale}
      styleSheetKeys={styleKeysToLoad}
    />,
  ])

  setBodyAttributes({
    className: bodyClassNames,
  })
}

export const wrapRootElement: GatsbySSR['wrapRootElement'] = ({ element }) => (
  <SwanConfiguration>{element}</SwanConfiguration>
)

import { graphql, HeadProps, PageProps } from 'gatsby'

type QueryDataType = {
  pageData: {
    title: string
  }
}
type PageContext = {
  locale: string
  slug: string
}

const PageOrTemplate = ({
  data,
  pageContext,
}: PageProps<QueryDataType, PageContext>) => {
  return <div>Page Content</div>
}

export default PageOrTemplate

export const Head = ({ data }: HeadProps<QueryDataType, PageContext>) => {
  return <title>{data.pageData.title}</title>
}

export const query = graphql`
  query PageOrTemplateQuery {
    pageData: someGraphqlMethod(slug: {current: {eq: $slug}}) {
      title
    }
  }
`

import { graphql, HeadProps, PageProps } from 'gatsby'

type QueryDataType = {
  pageData: {
    title: string
  }
}
type PageContext = {
  locale: string
  slug: string
}

const PageOrTemplate = ({
  data,
  pageContext,
}: PageProps<QueryDataType, PageContext>) => {
  return <div>Page Content</div>
}

export default PageOrTemplate

export const Head = ({ data }: HeadProps<QueryDataType, PageContext>) => {
  return <title>{data.pageData.title}</title>
}

export const query = graphql`
  query PageOrTemplateQuery {
    pageData: someGraphqlMethod(slug: {current: {eq: $slug}}) {
      title
    }
  }
`

SwanProvider

It's a component that acts as a configuration hub for the SWAN. It wraps your application and makes global settings, like asset paths and link components, available to all SWAN components via React's Context API.

It takes the following props:

pathType (optional)

Controls how asset files are referenced. It can take two possible values: hashed | versioned exported via an enum SwanPathTypeEnum. Each asset is stored at two paths: one using the content hash and one using the package version. It defaults to hashed, which is the recommended value. Not all asset files change between different versions of SWAN. Therefore, if they have the same content, they will also have the same hash across different versions of SWAN. By default, it uses hashed path.

swanTenant (optional)

Specifies which tenant (i.e., site) to load assets for.

In Swan, only vistaprint is currently supported.
Typically, only needed in production, so assets resolve correctly.

swanLocale (optional)

Specifies the locale, which determines the domain (TLD) from which assets are loaded.

Valid values include standard locale codes like: en-US, en-gb, fr-FR, de-de, etc.
Ensure assets are fetched from the correct localized endpoint in production builds. Each locale maps to a specific production domain, e.g.:

{
  "en-US": "www.vistaprint.com",
  "en-GB": "www.vistaprint.co.uk",
  "fr-FR": "www.vistaprint.fr",
  "de-DE": "www.vistaprint.de"
}

{
  "en-US": "www.vistaprint.com",
  "en-GB": "www.vistaprint.co.uk",
  "fr-FR": "www.vistaprint.fr",
  "de-DE": "www.vistaprint.de"
}

swanBaseUrl (optional)

Controls where SWAN assets are loaded from.

If you provide swanTenant + swanLocale, swanBaseUrl is generated automatically using them.
You can use this prop to explicitly set a base URL if needed.
If both swanTenant + swanLocale and swanBaseUrl are provided, the preference is given to the swanBaseUrl.
By default, SWAN uses the https://swan.prod.merch.vpsvc.com domain as the swanBaseUrl. But we've also made sure that our assets are available via each of our production domains (e.g. vistaprint.ie) on a proxy path /swan/. So, when building for production, we recommend that you specify the appropriate domain via the domain option in SwanProvider’s swanBaseUrl prop.

import { SWAN_BASE_URL_MAP } from '@vp/swan'

const baseURL = SWAN_BASE_URL_MAP.vistaprint.com // https://www.vistaprint.com/swan/

import { SWAN_BASE_URL_MAP } from '@vp/swan'

const baseURL = SWAN_BASE_URL_MAP.vistaprint.com // https://www.vistaprint.com/swan/

Why this matters:
When assets are served from the same domain as your app, the browser can reuse its existing connection instead of opening a new one for a different domain. This reduces connection overhead, speeds up asset loading, and improves overall performance.

For best results, configure your app and swanBaseUrl to use the same domain.

globalLinkComponent (optional)

Defines the default component used by the Swan Link component.

In single-page applications, it’s common to rely on a routing library (like React Router, Next.js, or Gatsby) for client-side navigation. These libraries ship their own Link components, which must be used instead of plain <a> tags. Why? Because they handle navigation internally (and sometimes prefetching), bypassing the browser’s default anchor behavior for better performance and user experience.

By default, Swan Link renders a regular <a>. But since SWAN components are configurable, you can replace that with your framework’s routing component.

You can tell a Swan Link component to render a NextJsLink rather than an <a> like this:

import { Link } from '@vp/swan'
import NextJsLink from 'next/link'

function MyComponent() {
  return (
    <Link as={NextJsLink} href="#">
      Navigate somewhere
    </Link>
  )
}

import { Link } from '@vp/swan'
import NextJsLink from 'next/link'

function MyComponent() {
  return (
    <Link as={NextJsLink} href="#">
      Navigate somewhere
    </Link>
  )
}

If you want all Swan Link components to use NextJsLink (or any other routing component) automatically, set it once via the globalLinkComponent prop on SwanProvider:

import { SwanProvider, Link } from '@vp/swan'
import NextJsLink from 'next/link'

function TopLevelConfiguration() {
  return (
    <SwanProvider globalLinkComponent={NextJsLink}>
      <App />
      <SomeComponent />
    </SwanProvider>
  )
}

function SomeComponent() {
  return <Link href="/some_url">Some URL rendered via NextJs Link</Link>
}

import { SwanProvider, Link } from '@vp/swan'
import NextJsLink from 'next/link'

function TopLevelConfiguration() {
  return (
    <SwanProvider globalLinkComponent={NextJsLink}>
      <App />
      <SomeComponent />
    </SwanProvider>
  )
}

function SomeComponent() {
  return <Link href="/some_url">Some URL rendered via NextJs Link</Link>
}

Now, every Swan Link inside <SwanProvider> will use NextJsLink by default, no need to pass the component via as prop each time.

SwanHead

Handles stylesheet loading and font setup. It takes the following props:

swanBaseUrl (Optional)

Tries to read from SwanProvider when used as a child. For cases where SwanHead is used outside the SwanProvider like (NextJs) _document.js or gatsby-ssr pass the appropriate value. By default, it uses the https://swan.prod.merch.vpsvc.com domain as the swanBaseUrl.

swanPathType (Optional)

Defaults to SwanProvider's value if inside the SwanProvider else, it defaults to hashed.

styleSheetKeys (Required)

List of all the stylesheets that it needs to load. Swan doesn't support auto-loading of styles. So pass all the values. It defaults to loading all the CSS.

fontNames (Optional)

You can control which fonts Swan loads by explicitly listing them.

Default behavior: If you don’t configure anything, Swan will load all available fonts.
Custom behavior: If you provide a fontNames list, Swan will load only the fonts you specify.
- This means you must include all fonts you need, not just the ones you want to add.

For example, if your application uses both Graphik and Tiempos, configure it like this:

<SwanHead fontNames={[SwanFontNameEnum.Graphik, SwanFontNameEnum.Tiempos]} />

<SwanHead fontNames={[SwanFontNameEnum.Graphik, SwanFontNameEnum.Tiempos]} />

renderWith (optional)

You can control which custom head management component should be used. In React 19 or above, if not provided, Swan defaults to React’s native head management API. And below React 19, it defaults to React.Fragment. When using a framework like NextJs, we can use its Head component. In non-framework projects, you can use the default or Helmet from react-helmet-async

Let you choose a custom component for managing the <head> of a document. If you don't specify one, Swan uses React's native head management API in React 19 and later. For older React versions, it defaults to a React.Fragment. When you're using a framework like NextJs, you should use its built-in <Head> component. For projects without a framework, you can use the default setting or a library like react-helmet-async.

renderStyleContentAsChildren (optional)

You can control how <style> tag content is rendered. Instead of using dangerouslySetInnerHTML, it renders the content as a child. This is useful when you are working with libraries like react-helmet that expect the style content to be a child of the <style> tag.

Managing `<head>` in React projects

If your project is built with a modern framework, like Next.js, or other, you should always use the framework's built-in solution for managing the <head>. These tools are designed to work seamlessly with the framework's server-side rendering (SSR) and routing, providing the best performance and a unified DX.
If you’re not using a framework, then you can prefer React19's new built-in head management APIs (like meta, link, or title).

If you are working on a project with a version of React older than 19, you will need to use a library to manage your document's head. The recommended choice is react-helmet-async. It is a modern, actively maintained successor to the deprecated react-helmet and is fully compatible with older React versions.

Page Meta Tag

The SWAN library simplifies the management of essential page meta tags as part of the SwanHead component, ensuring optimal performance and functionality for your web application.

With SWAN, you no longer need to manually include and configure these meta tags individually. The library takes care of the following meta tags for you within the SwanHead component:

<>
  <meta key="charset" charSet="UTF-8" />
  <meta
    key="viewport"
    name="viewport"
    content="width=device-width, initial-scale=1.0"
  />
  <meta
    key="telephone format detection"
    name="format-detection"
    content="telephone=no"
  />
  <meta
    key={SWAN_VERSION_META_NAME}
    name={SWAN_VERSION_META_NAME}
    content={SWAN_VERSION}
  />
  <link
    rel="shortcut icon"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/favicon.ico"
  />
  <link
    rel="apple-touch-icon"
    sizes="152x152"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-152x152.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="120x120"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-120x120.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="76x76"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-76x76.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="60x60"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-60x60.png"
  />
</>

<>
  <meta key="charset" charSet="UTF-8" />
  <meta
    key="viewport"
    name="viewport"
    content="width=device-width, initial-scale=1.0"
  />
  <meta
    key="telephone format detection"
    name="format-detection"
    content="telephone=no"
  />
  <meta
    key={SWAN_VERSION_META_NAME}
    name={SWAN_VERSION_META_NAME}
    content={SWAN_VERSION}
  />
  <link
    rel="shortcut icon"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/favicon.ico"
  />
  <link
    rel="apple-touch-icon"
    sizes="152x152"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-152x152.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="120x120"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-120x120.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="76x76"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-76x76.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="60x60"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-60x60.png"
  />
</>

By leveraging the SWAN library's meta tag management capabilities, you can focus on developing your application without worrying about the intricate details of meta tag setup.

getRootClassNames

Swan is designed to be interoperable with other design systems, enabling incremental adoption. To support this, all Swan-related styles are scoped under a root swan class.

Full-page usage → Apply the generated class names to the <body> tag if you want Swan styles applied globally.
Incremental adoption → Apply the class names only to the container element where Swan components are rendered, so other parts of your app remain unaffected.

This function accepts a configuration object with the following options:

standardMode?: boolean – Enables Swan’s standard theme mode (default: false).
darkMode?: boolean – Enables Swan’s dark theme mode (default: false).

() => {
  const defaultClassName = getRootClassNames()
  const withDarkMode = getRootClassNames({ darkMode: true })
  return (
    <>
      <div>
        <em>Default ClassNames:</em> <code>{defaultClassName}</code>
      </div>
      <div>
        <em>withDarkMode ClassNames:</em> <code>{withDarkMode}</code>
      </div>
    </>
  )
}

() => {
  const defaultClassName = getRootClassNames()
  const withDarkMode = getRootClassNames({ darkMode: true })
  return (
    <>
      <div>
        <em>Default ClassNames:</em> <code>{defaultClassName}</code>
      </div>
      <div>
        <em>withDarkMode ClassNames:</em> <code>{withDarkMode}</code>
      </div>
    </>
  )
}

useBrowserClasses

Deprecated

Browser-based CSS injection can cause flicker during server-side rendering (SSR) and should be avoided.

This accepts an optional boolean parameter that will add the browser's name as a class name on the <head> tag. For instance, if you are using Firefox, you should see the class swan-firefox on the <head> tag.

We account for the following browsers by analyzing the navigator.userAgent:

Safari
Firefox
IE
Edge (pre-Chromium, and Chromium-based)

() => {
  const cn = useBrowserClasses()
  return (
    <div>
      <em>Browser Class Name : </em> <code>{cn}</code>
    </div>
  )
}

() => {
  const cn = useBrowserClasses()
  return (
    <div>
      <em>Browser Class Name : </em> <code>{cn}</code>
    </div>
  )
}

Testing

waitForStyles

When testing SWAN components, especially in a browser-based testing solution like Playwright or Cypress, you may need to wait for SWAN styles to be loaded before running your test assertions. We provide a testing utility called waitForStyles that does exactly what it's called - it returns a promise that resolves when the SWAN-style keys are loaded. To use, put await waitForStyles() in your test.