|
| 1 | +## How to use the breakpoints |
| 2 | + |
| 3 | +In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography, spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints. |
| 4 | + |
| 5 | +Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications. |
| 6 | + |
| 7 | +### Sass |
| 8 | + |
| 9 | +To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package: |
| 10 | + |
| 11 | + |
| 12 | +```scss |
| 13 | +// from @hashicorp/design-system-components package |
| 14 | +@use "mixins/breakpoints" as *; |
| 15 | +``` |
| 16 | + |
| 17 | +!!! info |
| 18 | + |
| 19 | +If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support. |
| 20 | + |
| 21 | +!!! |
| 22 | + |
| 23 | +Once the file is imported, you will have access to the Sass helpers described below. |
| 24 | + |
| 25 | +#### Mixins |
| 26 | + |
| 27 | +Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins: |
| 28 | + |
| 29 | +- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach) |
| 30 | +- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach) |
| 31 | +- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints |
| 32 | + |
| 33 | +Here is an example of how the mixins could be used in a mobile-first responsive layout: |
| 34 | + |
| 35 | +```scss |
| 36 | +// from @hashicorp/design-system-components package |
| 37 | +@use "mixins/breakpoints" as *; |
| 38 | + |
| 39 | +.my-responsive-layout { |
| 40 | + // this is the default behavior, that covers the range 0px–767px |
| 41 | + display: flex; |
| 42 | + direction: column; |
| 43 | + gap: 1rem; |
| 44 | + |
| 45 | + // at 768px the layout changes, from a vertical stack to an horizontal one |
| 46 | + @include hds-breakpoint-above('md') { |
| 47 | + direction: row; |
| 48 | + } |
| 49 | + |
| 50 | + // at larger viewports we increase the spacing between the items |
| 51 | + @include hds-breakpoint-above('xl') { |
| 52 | + gap: 2rem; |
| 53 | + } |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +The same layout could be achieved using a desktop-first approach in a similar way: |
| 58 | + |
| 59 | +```scss |
| 60 | +// from @hashicorp/design-system-components package |
| 61 | +@use "mixins/breakpoints" as *; |
| 62 | + |
| 63 | +.my-responsive-layout { |
| 64 | + // this is the default behavior |
| 65 | + display: flex; |
| 66 | + direction: row; |
| 67 | + gap: 2rem; |
| 68 | + |
| 69 | + // at smaller viewports we decrease the spacing between the items |
| 70 | + @include hds-breakpoint-below('xl') { |
| 71 | + gap: 1rem; |
| 72 | + } |
| 73 | + |
| 74 | + // at 768px the layout changes, from an horizontal stack to a vertical one |
| 75 | + @include hds-breakpoint-below('md') { |
| 76 | + direction: column; |
| 77 | + } |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +Of course, these are oversimplified examples. In your implementation, you will have to choose which mixin is best suited to achieve the desired responsive layout. This will depend on the design specifications, the context of the layout within the page, and how it relates with other UI elements. |
| 82 | + |
| 83 | +#### Key/Value Map |
| 84 | + |
| 85 | +For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used: |
| 86 | + |
| 87 | +```scss |
| 88 | +// explicit import of `map` module (required by Sass) |
| 89 | +@use "sass:map"; |
| 90 | +// from @hashicorp/design-system-components package |
| 91 | +@use "mixins/breakpoints" as *; |
| 92 | + |
| 93 | +@each $name, $size in $hds-breakpoints { |
| 94 | + .my-custom-breakpoint-class--#{$name} { |
| 95 | + // here you have access to the breakpoint name and its value (width in px) |
| 96 | + } |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +### JavaScript |
| 101 | + |
| 102 | +We also provide helpers in case you need to access the breakpoints names/values in JavaScript code. |
| 103 | + |
| 104 | +You have access to the list of breakpoint names and values using the `hdsBreakpoints` map: |
| 105 | + |
| 106 | +```javascript{data-execute=false} |
| 107 | +import { hdsBreakpoints } from '@hashicorp/design-system-components/utils/hds-breakpoints'; |
| 108 | + |
| 109 | +// do something with a specific breakpoint value |
| 110 | +const myBreakpoint1 = hdsBreakpoints['xl'].value; // numeric (eg. 1440) |
| 111 | +const myBreakpoint2 = hdsBreakpoints['lg'].px; // size in px (eg. 1088px) |
| 112 | +const myBreakpoint3 = hdsBreakpoints['sm'].rem; // size in rem (eg. 30rem) |
| 113 | + |
| 114 | +// loop over all the breakpoints |
| 115 | +Object.entries(hdsBreakpoints).forEach(([name, sizes]) => { |
| 116 | + // do something with a specific breakpoint value in px |
| 117 | + const myBreakpointSizePx = sizes.px; |
| 118 | +}); |
| 119 | +``` |
0 commit comments