Responsive System

SWAN has responsiveness embedded in its Typography, tokens, components, and props. The default responsiveness of SWAN should not be overridden, but it’s expected that users will add their own custom responsive styling as necessary.

CSS-based approaches (including core props) are preferred over JS approaches, as they avoid impacting page load, flickering, and issues with SSR.

Breakpoints

SWAN has a mobile-first responsive system with five breakpoints. These breakpoints are available as tokens for SASS and JavaScript usage.

Core Props

Most of the core props offered in SWAN, such as margin , textAlign and display, have built-in responsive support. This allows finer control depending on the breakpoint.

Core props are mobile first - setting a value for sm will apply the same value for md, lg, etc.

Some typography-related props intentionally do not allow this customization, as they are embedded into the tokens themselves.

Refer to Core Props for more information.

The preview has been updated.

CopySharePrettify

<Box
  bgc={{ xs: 'success', lg: 'error' }}
  padding={{ xs: 4, md: 8 }}
  textAlign={{ lg: 'right' }}
>
  Resize the browser to see responsive Core Props in action
</Box>

<Box bgc={{ xs: 'success', lg: 'error' }} padding={{ xs: 4, md: 8 }} textAlign={{ lg: 'right' }} > Resize the browser to see responsive Core Props in action </Box>

Tokens

Many tokens change their value depending on the breakpoint. Note that as tokensRaw does not abstract a CSS Custom Property, these do not change on breakpoint changes.

breakpoint tokens define raw values, while mq tokens act as helper functions for @media rules. The latter combine a range (eq, gt, ...) with a screen size to target one or more breakpoints.

Both of these can be used to write breakpoint-specific CSS as needed. When using mq tokens with SASS, they will need to be interpolated per the example below.

Refer to All Tokens for more information.

CopyShare

@media #{tokens.$swan-sem-mq-lte-sm} {
  /* CSS that only applies to Small screens or smaller */
}

@media #{tokens.$swan-sem-mq-lte-sm} { /* CSS that only applies to Small screens or smaller */ }

In SASS, you can also use the breakpoint-mixins function:

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 */ }

Components

In addition to Core Props having responsive support, specific components with crucial props are also responsive.

• Grid - Column Spanning, offsetting, push, pull, and sticky
• Carousel's slidesToShow
• FlexBox - all props
• Hidden - prop-based visibility
• Visible - prop-based visibility

Server-Side Rendering

The above-mentioned ways of handling responsiveness should cover most of your use cases and are also the recommended ways of supporting responsiveness, as they are CSS-first (yes, all of them). And if you use them, everything works well with server-side rendering.

We also provide JavaScript-based solutions discussed below, but these are problematic for SSR, as they are JS-driven and can’t detect screen size until the first render. So everything renders based on the default value set (xs for mobile-first), and as the page hydrates, based on the browser width, the value of the function output may change and thus cause a flickering issue, hydration mismatch, and can also lead to poor LCP.

JavaScript Solutions

SWAN offers React utilities that allow for more control around the responsive system in JSX. These should only be used when the aforementioned methods aren't available.

Prerequisites

You need to wrap your code with ScreenClassProvider. You can wrap it either at the root of your application if you are using the below methods multiple times in your application, or you can simply wrap it in a particular scope of functionality.

useScreenClass Hook

In combination with the ScreenClassProvider component, the useScreenClass hook can be used to get the current screen size inside of your React components.

Use these only for the cases where you have small changes or not directly affecting page loads.

CopyShare

import { useScreenClass } from '@vp/swan'

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

function SomeComponent() {
  const screenClass = useScreenClass()

  console.log(screenClass) // e.g. 'xs'
  console.log(propsByScreenClass[screenClass]) // e.g. '1'
}

import { useScreenClass } from '@vp/swan' const propsByScreenClass = { xs: { propName: 1 }, sm: { propName: 2 }, md: { propName: 3 }, lg: { propName: 3 }, xl: { propName: 4 }, } function SomeComponent() { const screenClass = useScreenClass() console.log(screenClass) // e.g. 'xs' console.log(propsByScreenClass[screenClass]) // e.g. '1' }

The useScreenClass hook defaults to xs until ScreenClassProvider initializes. You can use useIsScreenClassInitialized to check if it has initialized.

CopyShare

import { useIsScreenClassInitialized } from '@vp/swan'

function SomeComponent() {
  const isScreenClassInitialized = useIsScreenClassInitialized()

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

import { useIsScreenClassInitialized } from '@vp/swan' function SomeComponent() { const isScreenClassInitialized = useIsScreenClassInitialized() console.log(isScreenClassInitialized) // initially false and then true after initialization }

responsive function

The responsive hook can be used to make an entire component responsive. In most cases, this should not be used in favor of other approaches mentioned on this page.

CopyShare

import { responsive, SkeletonText } from '@vp/swan'

const ResponsiveSkeletonText = responsive(SkeletonText)

function SomeComponent() {
  return (
    <ResponsiveSkeletonText
      xs={{ width: 'narrow' }}
      sm={{ width: 'narrow' }}
      md={{ width: 'standard' }}
      lg={{ width: 'standard' }}
    />
  )
}

import { responsive, SkeletonText } from '@vp/swan' const ResponsiveSkeletonText = responsive(SkeletonText) function SomeComponent() { return ( <ResponsiveSkeletonText xs={{ width: 'narrow' }} sm={{ width: 'narrow' }} md={{ width: 'standard' }} lg={{ width: 'standard' }} /> ) }