Responsive System

SWAN defines five screen size ranges:

In the React API, use SWAN’s Responsive System to make your components adjust responsively based on these screen sizes. It is based on responsive-system.

In the Vanilla API, you can still use our design tokens in your stylesheets to adjust your CSS based on the screen size. Refer to “Design Tokens and Stylesheets” below.

Usage

First, render the ScreenClassProvider at the root of your app:

CopyShare

// index.tsx import { ScreenClassProvider } from '@vp/swan' function Root() { return ( <ScreenClassProvider> <App /> </ScreenClassProvider> ) }

// index.tsx
import { ScreenClassProvider } from '@vp/swan'

function Root() {
  return (
    <ScreenClassProvider>
      <App />
    </ScreenClassProvider>
  )
}

useScreenClass

Use the useScreenClass hook in your components to find out the current screen size: "xs", "sm", "md", "lg" or "xl". You can then use this value to adjust props based on screen size:

CopyShare

// some-component.tsx import { useScreenClass, Carousel } from '@vp/swan' const propsByScreenClass = { xs: { slidesToShow: 1 }, sm: { slidesToShow: 2 }, md: { slidesToShow: 3 }, lg: { slidesToShow: 3 }, xl: { slidesToShow: 4 }, } function SomeComponent() { const screenClass = useScreenClass() console.log(screenClass) // "xs" or "sm" or "md" or "lg" or "xl" return <Carousel {...propsByScreenClass[screenClass]} /> }

// some-component.tsx
import { useScreenClass, Carousel } from '@vp/swan'

const propsByScreenClass = {
  xs: { slidesToShow: 1 },
  sm: { slidesToShow: 2 },
  md: { slidesToShow: 3 },
  lg: { slidesToShow: 3 },
  xl: { slidesToShow: 4 },
}

function SomeComponent() {
  const screenClass = useScreenClass()

  console.log(screenClass) // "xs" or "sm" or "md" or "lg" or "xl"

  return <Carousel {...propsByScreenClass[screenClass]} />
}

useIsScreenClassInitialized

By default, the useScreenClass hook returns the value "xs" until the ScreenClassProvider has initialized. Use useIsScreenClassInitialized to tell if the ScreenClassProvider has actually initialized yet. It returns a boolean value.

Note that during server-side rendering, useIsScreenClassInitialized will always return false.

CopyShare

// some-component.tsx import { useIsScreenClassInitialized, Carousel } from '@vp/swan' function SomeComponent() { const isScreenClassInitialized = useIsScreenClassInitialized() console.log(isScreenClassInitialized) // initially false and then true after initialization return <Carousel someProps /> }

// some-component.tsx
import { useIsScreenClassInitialized, Carousel } from '@vp/swan'

function SomeComponent() {
  const isScreenClassInitialized = useIsScreenClassInitialized()

  console.log(isScreenClassInitialized) // initially false and then true after initialization

  return <Carousel someProps />
}

responsive

Use the responsive function to make your entire component responsive:

CopyShare

// some-component.tsx import { responsive, Carousel } from '@vp/swan' const ResponsiveCarousel = responsive(Carousel) function SomeComponent() { return ( <ResponsiveCarousel xs={{ slidesToShow: 1 }} sm={{ slidesToShow: 2 }} md={{ slidesToShow: 3 }} lg={{ slidesToShow: 3 }} /> ) }

// some-component.tsx
import { responsive, Carousel } from '@vp/swan'

const ResponsiveCarousel = responsive(Carousel)

function SomeComponent() {
  return (
    <ResponsiveCarousel
      xs={{ slidesToShow: 1 }}
      sm={{ slidesToShow: 2 }}
      md={{ slidesToShow: 3 }}
      lg={{ slidesToShow: 3 }}
    />
  )
}

responsive components use the mobile-first pattern, where a value for one screen size will be automatically applied to any larger screen sizes as well. In our example above, md and lg screens both need to have slidesToShow = 3, so we can omit the lg override here, since responsive will apply the md value to lg and xl:

CopyShare

// some-component.tsx import { responsive, Carousel } from '@vp/swan' const ResponsiveCarousel = responsive(Carousel) function SomeComponent() { return ( <ResponsiveCarousel xs={{ slidesToShow: 1 }} // affects xs _and larger_ sm={{ slidesToShow: 2 }} // affects sm _and larger_ md={{ slidesToShow: 3 }} // affects md _and larger_ /> ) }

// some-component.tsx
import { responsive, Carousel } from '@vp/swan'

const ResponsiveCarousel = responsive(Carousel)

function SomeComponent() {
  return (
    <ResponsiveCarousel
      xs={{ slidesToShow: 1 }} // affects xs _and larger_
      sm={{ slidesToShow: 2 }} // affects sm _and larger_
      md={{ slidesToShow: 3 }} // affects md _and larger_
    />
  )
}

In addition, since our responsive component is mobile-first, we don't need to explicitly specify an override for xs, since xs is the default configuration for the component. So we can write it like this:

CopyShare

// some-component.tsx import { responsive, Carousel } from '@vp/swan' const ResponsiveCarousel = responsive(Carousel) function SomeComponent() { return ( <ResponsiveCarousel slidesToShow={1} sm={{ slidesToShow: 2 }} // affects sm _and larger_ md={{ slidesToShow: 3 }} // affects md _and larger_ /> ) }

// some-component.tsx
import { responsive, Carousel } from '@vp/swan'

const ResponsiveCarousel = responsive(Carousel)

function SomeComponent() {
  return (
    <ResponsiveCarousel
      slidesToShow={1}
      sm={{ slidesToShow: 2 }} // affects sm _and larger_
      md={{ slidesToShow: 3 }} // affects md _and larger_
    />
  )
}

Server-side rendering

During SSR, we cannot detect the screen size upon first render, so the Responsive System will default to Extra-Small. This may result in a flicker when the page is hydrated in the browser, since the Responsive System will then update the page using the actual screen size. Therefore, if your page is using SSR, avoid using different props for different screen sizes whenever possible.

Note that this issue applies only to using JavaScript to adjust content by screen size. CSS media queries (see below) will always use the actual browser width, so will be unaffected by this.

Design Tokens and Stylesheets

Use SWAN’s design tokens and mixins from the ~@vp/swan/mixins/scss/breakpoint-mixins import path in your application’s stylesheets to construct media queries that will make some CSS only apply to a certain screen size(s):

CopyShare

@use '~@vp/swan/mixins/scss/breakpoint-mixins'; @include breakpoint-mixins.media-query('lteSm') { /* CSS that only applies to Small screens or smaller */ }

@use '~@vp/swan/mixins/scss/breakpoint-mixins';

@include breakpoint-mixins.media-query('lteSm') {
  /* CSS that only applies to Small screens or smaller */
}

The mixin’s values must follow one of these formats:

• A screen size (one of xs, sm, md, lg, or xl).
• A prefix (one of eq, gt, lt, or lte) followed by a screen size (one of Xs, Sm, Md, Lg, or Xl).