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.
Name | Start | End |
xs | 0px | 767px |
sm | 768px | 1023px |
md | 1024px | 1439px |
lg | 1440px | 1919px |
xl | 1920px |
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.
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.
In SASS, you can also use the breakpoint-mixins
function:
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
JavaScript solutions (and SSR implications)
The above-mentioned ways of handling responsiveness are the recommended ways of supporting responsiveness, as they are powered by CSS. If your use case is not covered, we also provide JavaScript-based solutions discussed below.
JS-driven solutions should generally be avoided for styling if your page is using Server-Side Rendering (SSR). JavaScript cannot detect the screen size until the first render, meaning the first render always assumes a xs
screen size.
This can cause a flickering issue, hydration mismatch, and lead to poor LCP.
Use the below only for small enhancements, fine-tuning, or elements that can change dynamically after page load. Avoid using them for layout-impacting conditional renders, which are better handled with the methods described above.
If nothing fits, Hidden
& Visible
should still be able to help out of the conditional screen-based rendering.
Prerequisites
Wrap your code with ScreenClassProvider
. If you use the methods below in multiple places, wrap it at the root of your application. Otherwise, wrap only the specific part of your code that needs this functionality.
useScreenClass Hook
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 are not directly affecting page loads.
The useScreenClass
hook defaults to xs
until ScreenClassProvider initializes. You can use useIsScreenClassInitialized
to check if it has initialized.
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.