From c1d5a801b4bc66e3866f815be00e11d1b20d3539 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 24 Jun 2023 14:44:36 +0200 Subject: Adding upstream version 5.3.0+dfsg. Signed-off-by: Daniel Baumann --- site/content/docs/5.3/utilities/api.md | 623 ++++++++++++++++++++ site/content/docs/5.3/utilities/background.md | 150 +++++ site/content/docs/5.3/utilities/borders.md | 194 +++++++ site/content/docs/5.3/utilities/colors.md | 141 +++++ site/content/docs/5.3/utilities/display.md | 114 ++++ site/content/docs/5.3/utilities/flex.md | 664 ++++++++++++++++++++++ site/content/docs/5.3/utilities/float.md | 48 ++ site/content/docs/5.3/utilities/interactions.md | 42 ++ site/content/docs/5.3/utilities/link.md | 105 ++++ site/content/docs/5.3/utilities/object-fit.md | 63 ++ site/content/docs/5.3/utilities/opacity.md | 33 ++ site/content/docs/5.3/utilities/overflow.md | 99 ++++ site/content/docs/5.3/utilities/position.md | 130 +++++ site/content/docs/5.3/utilities/shadows.md | 30 + site/content/docs/5.3/utilities/sizing.md | 62 ++ site/content/docs/5.3/utilities/spacing.md | 154 +++++ site/content/docs/5.3/utilities/text.md | 160 ++++++ site/content/docs/5.3/utilities/vertical-align.md | 48 ++ site/content/docs/5.3/utilities/visibility.md | 37 ++ site/content/docs/5.3/utilities/z-index.md | 50 ++ 20 files changed, 2947 insertions(+) create mode 100644 site/content/docs/5.3/utilities/api.md create mode 100644 site/content/docs/5.3/utilities/background.md create mode 100644 site/content/docs/5.3/utilities/borders.md create mode 100644 site/content/docs/5.3/utilities/colors.md create mode 100644 site/content/docs/5.3/utilities/display.md create mode 100644 site/content/docs/5.3/utilities/flex.md create mode 100644 site/content/docs/5.3/utilities/float.md create mode 100644 site/content/docs/5.3/utilities/interactions.md create mode 100644 site/content/docs/5.3/utilities/link.md create mode 100644 site/content/docs/5.3/utilities/object-fit.md create mode 100644 site/content/docs/5.3/utilities/opacity.md create mode 100644 site/content/docs/5.3/utilities/overflow.md create mode 100644 site/content/docs/5.3/utilities/position.md create mode 100644 site/content/docs/5.3/utilities/shadows.md create mode 100644 site/content/docs/5.3/utilities/sizing.md create mode 100644 site/content/docs/5.3/utilities/spacing.md create mode 100644 site/content/docs/5.3/utilities/text.md create mode 100644 site/content/docs/5.3/utilities/vertical-align.md create mode 100644 site/content/docs/5.3/utilities/visibility.md create mode 100644 site/content/docs/5.3/utilities/z-index.md (limited to 'site/content/docs/5.3/utilities') diff --git a/site/content/docs/5.3/utilities/api.md b/site/content/docs/5.3/utilities/api.md new file mode 100644 index 0000000..aa7d6b8 --- /dev/null +++ b/site/content/docs/5.3/utilities/api.md @@ -0,0 +1,623 @@ +--- +layout: docs +title: Utility API +description: The utility API is a Sass-based tool to generate utility classes. +group: utilities +aliases: "/docs/5.3/utilities/" +toc: true +--- + +Bootstrap utilities are generated with our utility API and can be used to modify or extend our default set of utility classes via Sass. Our utility API is based on a series of Sass maps and functions for generating families of classes with various options. If you're unfamiliar with Sass maps, read up on the [official Sass docs](https://sass-lang.com/documentation/values/maps) to get started. + +The `$utilities` map contains all our utilities and is later merged with your custom `$utilities` map, if present. The utility map contains a keyed list of utility groups which accept the following options: + +{{< bs-table "table table-utilities" >}} +| Option | Type | Default value | Description | +| --- | --- | --- | --- | +| [`property`](#property) | **Required** | – | Name of the property, this can be a string or an array of strings (e.g., horizontal paddings or margins). | +| [`values`](#values) | **Required** | – | List of values, or a map if you don't want the class name to be the same as the value. If `null` is used as map key, `class` is not prepended to the class name. | +| [`class`](#class) | Optional | null | Name of the generated class. If not provided and `property` is an array of strings, `class` will default to the first element of the `property` array. If not provided and `property` is a string, the `values` keys are used for the `class` names. | +| [`css-var`](#css-variable-utilities) | Optional | `false` | Boolean to generate CSS variables instead of CSS rules. | +| [`css-variable-name`](#css-variable-utilities) | Optional | null | Custom un-prefixed name for the CSS variable inside the ruleset. | +| [`local-vars`](#local-css-variables) | Optional | null | Map of local CSS variables to generate in addition to the CSS rules. | +| [`state`](#states) | Optional | null | List of pseudo-class variants (e.g., `:hover` or `:focus`) to generate. | +| [`responsive`](#responsive) | Optional | `false` | Boolean indicating if responsive classes should be generated. | +| `rfs` | Optional | `false` | Boolean to enable [fluid rescaling with RFS]({{< docsref "/getting-started/rfs" >}}). | +| [`print`](#print) | Optional | `false` | Boolean indicating if print classes need to be generated. | +| `rtl` | Optional | `true` | Boolean indicating if utility should be kept in RTL. | +{{< /bs-table >}} + +## API explained + +All utility variables are added to the `$utilities` variable within our `_utilities.scss` stylesheet. Each group of utilities looks something like this: + +```scss +$utilities: ( + "opacity": ( + property: opacity, + values: ( + 0: 0, + 25: .25, + 50: .5, + 75: .75, + 100: 1, + ) + ) +); +``` + +Which outputs the following: + +```css +.opacity-0 { opacity: 0; } +.opacity-25 { opacity: .25; } +.opacity-50 { opacity: .5; } +.opacity-75 { opacity: .75; } +.opacity-100 { opacity: 1; } +``` + +### Property + +The required `property` key must be set for any utility, and it must contain a valid CSS property. This property is used in the generated utility's ruleset. When the `class` key is omitted, it also serves as the default class name. Consider the `text-decoration` utility: + +```scss +$utilities: ( + "text-decoration": ( + property: text-decoration, + values: none underline line-through + ) +); +``` + +Output: + +```css +.text-decoration-none { text-decoration: none !important; } +.text-decoration-underline { text-decoration: underline !important; } +.text-decoration-line-through { text-decoration: line-through !important; } +``` + +### Values + +Use the `values` key to specify which values for the specified `property` should be used in the generated class names and rules. Can be a list or map (set in the utilities or in a Sass variable). + +As a list, like with [`text-decoration` utilities]({{< docsref "/utilities/text#text-decoration" >}}): + +```scss +values: none underline line-through +``` + +As a map, like with [`opacity` utilities]({{< docsref "/utilities/opacity" >}}): + +```scss +values: ( + 0: 0, + 25: .25, + 50: .5, + 75: .75, + 100: 1, +) +``` + +As a Sass variable that sets the list or map, as in our [`position` utilities]({{< docsref "/utilities/position" >}}): + +```scss +values: $position-values +``` + +### Class + +Use the `class` option to change the class prefix used in the compiled CSS. For example, to change from `.opacity-*` to `.o-*`: + +```scss +$utilities: ( + "opacity": ( + property: opacity, + class: o, + values: ( + 0: 0, + 25: .25, + 50: .5, + 75: .75, + 100: 1, + ) + ) +); +``` + +Output: + +```css +.o-0 { opacity: 0 !important; } +.o-25 { opacity: .25 !important; } +.o-50 { opacity: .5 !important; } +.o-75 { opacity: .75 !important; } +.o-100 { opacity: 1 !important; } +``` + +If `class: null`, generates classes for each of the `values` keys: + +```scss +$utilities: ( + "visibility": ( + property: visibility, + class: null, + values: ( + visible: visible, + invisible: hidden, + ) + ) +); +``` + +Output: + +```css +.visible { visibility: visible !important; } +.invisible { visibility: hidden !important; } +``` + +### CSS variable utilities + +Set the `css-var` boolean option to `true` and the API will generate local CSS variables for the given selector instead of the usual `property: value` rules. Add an optional `css-variable-name` to set a different CSS variable name than the class name. + +Consider our `.text-opacity-*` utilities. If we add the `css-variable-name` option, we'll get a custom output. + +```scss +$utilities: ( + "text-opacity": ( + css-var: true, + css-variable-name: text-alpha, + class: text-opacity, + values: ( + 25: .25, + 50: .5, + 75: .75, + 100: 1 + ) + ), +); +``` + +Output: + +```css +.text-opacity-25 { --bs-text-alpha: .25; } +.text-opacity-50 { --bs-text-alpha: .5; } +.text-opacity-75 { --bs-text-alpha: .75; } +.text-opacity-100 { --bs-text-alpha: 1; } +``` + +### Local CSS variables + +Use the `local-vars` option to specify a Sass map that will generate local CSS variables within the utility class's ruleset. Please note that it may require additional work to consume those local CSS variables in the generated CSS rules. For example, consider our `.bg-*` utilities: + +```scss +$utilities: ( + "background-color": ( + property: background-color, + class: bg, + local-vars: ( + "bg-opacity": 1 + ), + values: map-merge( + $utilities-bg-colors, + ( + "transparent": transparent + ) + ) + ) +); +``` + +Output: + +```css +.bg-primary { + --bs-bg-opacity: 1; + background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important; +} +``` + +### States + +Use the `state` option to generate pseudo-class variations. Example pseudo-classes are `:hover` and `:focus`. When a list of states are provided, classnames are created for that pseudo-class. For example, to change opacity on hover, add `state: hover` and you'll get `.opacity-hover:hover` in your compiled CSS. + +Need multiple pseudo-classes? Use a space-separated list of states: `state: hover focus`. + +```scss +$utilities: ( + "opacity": ( + property: opacity, + class: opacity, + state: hover, + values: ( + 0: 0, + 25: .25, + 50: .5, + 75: .75, + 100: 1, + ) + ) +); +``` + +Output: + +```css +.opacity-0-hover:hover { opacity: 0 !important; } +.opacity-25-hover:hover { opacity: .25 !important; } +.opacity-50-hover:hover { opacity: .5 !important; } +.opacity-75-hover:hover { opacity: .75 !important; } +.opacity-100-hover:hover { opacity: 1 !important; } +``` + +### Responsive + +Add the `responsive` boolean to generate responsive utilities (e.g., `.opacity-md-25`) across [all breakpoints]({{< docsref "/layout/breakpoints" >}}). + +```scss +$utilities: ( + "opacity": ( + property: opacity, + responsive: true, + values: ( + 0: 0, + 25: .25, + 50: .5, + 75: .75, + 100: 1, + ) + ) +); +``` + +Output: + +```css +.opacity-0 { opacity: 0 !important; } +.opacity-25 { opacity: .25 !important; } +.opacity-50 { opacity: .5 !important; } +.opacity-75 { opacity: .75 !important; } +.opacity-100 { opacity: 1 !important; } + +@media (min-width: 576px) { + .opacity-sm-0 { opacity: 0 !important; } + .opacity-sm-25 { opacity: .25 !important; } + .opacity-sm-50 { opacity: .5 !important; } + .opacity-sm-75 { opacity: .75 !important; } + .opacity-sm-100 { opacity: 1 !important; } +} + +@media (min-width: 768px) { + .opacity-md-0 { opacity: 0 !important; } + .opacity-md-25 { opacity: .25 !important; } + .opacity-md-50 { opacity: .5 !important; } + .opacity-md-75 { opacity: .75 !important; } + .opacity-md-100 { opacity: 1 !important; } +} + +@media (min-width: 992px) { + .opacity-lg-0 { opacity: 0 !important; } + .opacity-lg-25 { opacity: .25 !important; } + .opacity-lg-50 { opacity: .5 !important; } + .opacity-lg-75 { opacity: .75 !important; } + .opacity-lg-100 { opacity: 1 !important; } +} + +@media (min-width: 1200px) { + .opacity-xl-0 { opacity: 0 !important; } + .opacity-xl-25 { opacity: .25 !important; } + .opacity-xl-50 { opacity: .5 !important; } + .opacity-xl-75 { opacity: .75 !important; } + .opacity-xl-100 { opacity: 1 !important; } +} + +@media (min-width: 1400px) { + .opacity-xxl-0 { opacity: 0 !important; } + .opacity-xxl-25 { opacity: .25 !important; } + .opacity-xxl-50 { opacity: .5 !important; } + .opacity-xxl-75 { opacity: .75 !important; } + .opacity-xxl-100 { opacity: 1 !important; } +} +``` + +### Print + +Enabling the `print` option will **also** generate utility classes for print, which are only applied within the `@media print { ... }` media query. + +```scss +$utilities: ( + "opacity": ( + property: opacity, + print: true, + values: ( + 0: 0, + 25: .25, + 50: .5, + 75: .75, + 100: 1, + ) + ) +); +``` + +Output: + +```css +.opacity-0 { opacity: 0 !important; } +.opacity-25 { opacity: .25 !important; } +.opacity-50 { opacity: .5 !important; } +.opacity-75 { opacity: .75 !important; } +.opacity-100 { opacity: 1 !important; } + +@media print { + .opacity-print-0 { opacity: 0 !important; } + .opacity-print-25 { opacity: .25 !important; } + .opacity-print-50 { opacity: .5 !important; } + .opacity-print-75 { opacity: .75 !important; } + .opacity-print-100 { opacity: 1 !important; } +} +``` + +## Importance + +All utilities generated by the API include `!important` to ensure they override components and modifier classes as intended. You can toggle this setting globally with the `$enable-important-utilities` variable (defaults to `true`). + +## Using the API + +Now that you're familiar with how the utilities API works, learn how to add your own custom classes and modify our default utilities. + +### Override utilities + +Override existing utilities by using the same key. For example, if you want additional responsive overflow utility classes, you can do this: + +```scss +$utilities: ( + "overflow": ( + responsive: true, + property: overflow, + values: visible hidden scroll auto, + ), +); +``` + +### Add utilities + +New utilities can be added to the default `$utilities` map with a `map-merge`. Make sure our required Sass files and `_utilities.scss` are imported first, then use the `map-merge` to add your additional utilities. For example, here's how to add a responsive `cursor` utility with three values. + +```scss +@import "bootstrap/scss/functions"; +@import "bootstrap/scss/variables"; +@import "bootstrap/scss/variables-dark"; +@import "bootstrap/scss/maps"; +@import "bootstrap/scss/mixins"; +@import "bootstrap/scss/utilities"; + +$utilities: map-merge( + $utilities, + ( + "cursor": ( + property: cursor, + class: cursor, + responsive: true, + values: auto pointer grab, + ) + ) +); + +@import "bootstrap/scss/utilities/api"; +``` + +### Modify utilities + +Modify existing utilities in the default `$utilities` map with `map-get` and `map-merge` functions. In the example below, we're adding an additional value to the `width` utilities. Start with an initial `map-merge` and then specify which utility you want to modify. From there, fetch the nested `"width"` map with `map-get` to access and modify the utility's options and values. + +```scss +@import "bootstrap/scss/functions"; +@import "bootstrap/scss/variables"; +@import "bootstrap/scss/variables-dark"; +@import "bootstrap/scss/maps"; +@import "bootstrap/scss/mixins"; +@import "bootstrap/scss/utilities"; + +$utilities: map-merge( + $utilities, + ( + "width": map-merge( + map-get($utilities, "width"), + ( + values: map-merge( + map-get(map-get($utilities, "width"), "values"), + (10: 10%), + ), + ), + ), + ) +); + +@import "bootstrap/scss/utilities/api"; +``` + +#### Enable responsive + +You can enable responsive classes for an existing set of utilities that are not currently responsive by default. For example, to make the `border` classes responsive: + +```scss +@import "bootstrap/scss/functions"; +@import "bootstrap/scss/variables"; +@import "bootstrap/scss/variables-dark"; +@import "bootstrap/scss/maps"; +@import "bootstrap/scss/mixins"; +@import "bootstrap/scss/utilities"; + +$utilities: map-merge( + $utilities, ( + "border": map-merge( + map-get($utilities, "border"), + ( responsive: true ), + ), + ) +); + +@import "bootstrap/scss/utilities/api"; +``` + +This will now generate responsive variations of `.border` and `.border-0` for each breakpoint. Your generated CSS will look like this: + +```css +.border { ... } +.border-0 { ... } + +@media (min-width: 576px) { + .border-sm { ... } + .border-sm-0 { ... } +} + +@media (min-width: 768px) { + .border-md { ... } + .border-md-0 { ... } +} + +@media (min-width: 992px) { + .border-lg { ... } + .border-lg-0 { ... } +} + +@media (min-width: 1200px) { + .border-xl { ... } + .border-xl-0 { ... } +} + +@media (min-width: 1400px) { + .border-xxl { ... } + .border-xxl-0 { ... } +} +``` + +#### Rename utilities + +Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting `class` of a given utility—for example, to rename `.ms-*` utilities to oldish `.ml-*`: + +```scss +@import "bootstrap/scss/functions"; +@import "bootstrap/scss/variables"; +@import "bootstrap/scss/variables-dark"; +@import "bootstrap/scss/maps"; +@import "bootstrap/scss/mixins"; +@import "bootstrap/scss/utilities"; + +$utilities: map-merge( + $utilities, ( + "margin-start": map-merge( + map-get($utilities, "margin-start"), + ( class: ml ), + ), + ) +); + +@import "bootstrap/scss/utilities/api"; +``` + +### Remove utilities + +Remove any of the default utilities with the [`map-remove()` Sass function](https://sass-lang.com/documentation/modules/map#remove). + +```scss +@import "bootstrap/scss/functions"; +@import "bootstrap/scss/variables"; +@import "bootstrap/scss/variables-dark"; +@import "bootstrap/scss/maps"; +@import "bootstrap/scss/mixins"; +@import "bootstrap/scss/utilities"; + +// Remove multiple utilities with a comma-separated list +$utilities: map-remove($utilities, "width", "float"); + +@import "bootstrap/scss/utilities/api"; +``` + +You can also use the [`map-merge()` Sass function](https://sass-lang.com/documentation/modules/map#merge) and set the group key to `null` to remove the utility. + +```scss +@import "bootstrap/scss/functions"; +@import "bootstrap/scss/variables"; +@import "bootstrap/scss/variables-dark"; +@import "bootstrap/scss/maps"; +@import "bootstrap/scss/mixins"; +@import "bootstrap/scss/utilities"; + +$utilities: map-merge( + $utilities, + ( + "width": null + ) +); + +@import "bootstrap/scss/utilities/api"; +``` + +### Add, remove, modify + +You can add, remove, and modify many utilities all at once with the [`map-merge()` Sass function](https://sass-lang.com/documentation/modules/map#merge). Here's how you can combine the previous examples into one larger map. + +```scss +@import "bootstrap/scss/functions"; +@import "bootstrap/scss/variables"; +@import "bootstrap/scss/variables-dark"; +@import "bootstrap/scss/maps"; +@import "bootstrap/scss/mixins"; +@import "bootstrap/scss/utilities"; + +$utilities: map-merge( + $utilities, + ( + // Remove the `width` utility + "width": null, + + // Make an existing utility responsive + "border": map-merge( + map-get($utilities, "border"), + ( responsive: true ), + ), + + // Add new utilities + "cursor": ( + property: cursor, + class: cursor, + responsive: true, + values: auto pointer grab, + ) + ) +); + +@import "bootstrap/scss/utilities/api"; +``` + +#### Remove utility in RTL + +Some edge cases make [RTL styling difficult](https://rtlstyling.com/posts/rtl-styling#common-things-that-might-not-work-for-rtl), such as line breaks in Arabic. Thus utilities can be dropped from RTL output by setting the `rtl` option to `false`: + +```scss +$utilities: ( + "word-wrap": ( + property: word-wrap word-break, + class: text, + values: (break: break-word), + rtl: false + ), +); +``` + +Output: + +```css +/* rtl:begin:remove */ +.text-break { + word-wrap: break-word !important; + word-break: break-word !important; +} +/* rtl:end:remove */ +``` + +This doesn't output anything in RTL, thanks to [the RTLCSS `remove` control directive](https://rtlcss.com/learn/usage-guide/control-directives/#remove). diff --git a/site/content/docs/5.3/utilities/background.md b/site/content/docs/5.3/utilities/background.md new file mode 100644 index 0000000..c17ed84 --- /dev/null +++ b/site/content/docs/5.3/utilities/background.md @@ -0,0 +1,150 @@ +--- +layout: docs +title: Background +description: Convey meaning through `background-color` and add decoration with gradients. +group: utilities +toc: true +--- + +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## Background color + +Similar to the contextual text color classes, set the background of an element to any contextual class. Background utilities **do not set `color`**, so in some cases you'll want to use `.text-*` [color utilities]({{< docsref "/utilities/colors" >}}). + +{{< callout info >}} +Background utilities like `.bg-*` that generated from our original `$theme-colors` Sass map don't yet respond to color modes, however, any `.bg-*-subtle` utility will. This will be resolved in v6. +{{< /callout >}} + +{{< example >}} +{{< colors.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +
.bg-{{ .name }}
+
.bg-{{ .name }}-subtle
+{{- end -}} +{{< /colors.inline >}} +

.bg-body-secondary

+

.bg-body-tertiary

+ +
.bg-body
+
.bg-black
+
.bg-white
+
.bg-transparent
+{{< /example >}} + +## Background gradient + +By adding a `.bg-gradient` class, a linear gradient is added as background image to the backgrounds. This gradient starts with a semi-transparent white which fades out to the bottom. + +Do you need a gradient in your custom CSS? Just add `background-image: var(--bs-gradient);`. + +{{< markdown >}} +{{< colors.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +
.bg-{{ .name }}.bg-gradient
+{{- end -}} +{{< /colors.inline >}} +
.bg-black.bg-gradient
+{{< /markdown >}} + +## Opacity + +{{< added-in "5.1.0" >}} + +As of v5.1.0, `background-color` utilities are generated with Sass using CSS variables. This allows for real-time color changes without compilation and dynamic alpha transparency changes. + +### How it works + +Consider our default `.bg-success` utility. + +```css +.bg-success { + --bs-bg-opacity: 1; + background-color: rgba(var(--bs-success-rgb), var(--bs-bg-opacity)) !important; +} +``` + +We use an RGB version of our `--bs-success` (with the value of `25, 135, 84`) CSS variable and attached a second CSS variable, `--bs-bg-opacity`, for the alpha transparency (with a default value `1` thanks to a local CSS variable). That means anytime you use `.bg-success` now, your computed `color` value is `rgba(25, 135, 84, 1)`. The local CSS variable inside each `.bg-*` class avoids inheritance issues so nested instances of the utilities don't automatically have a modified alpha transparency. + +### Example + +To change that opacity, override `--bs-bg-opacity` via custom styles or inline styles. + +{{< example >}} +
This is default success background
+
This is 50% opacity success background
+{{< /example >}} + +Or, choose from any of the `.bg-opacity` utilities: + +{{< example >}} +
This is default success background
+
This is 75% opacity success background
+
This is 50% opacity success background
+
This is 25% opacity success background
+
This is 10% opacity success background
+{{< /example >}} + +## CSS + +In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more. + +### Sass variables + +Most `background-color` utilities are generated by our theme colors, reassigned from our generic color palette variables. + +{{< scss-docs name="color-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-color-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="variable-gradient" file="scss/_variables.scss" >}} + +Grayscale colors are also available, but only a subset are used to generate any utilities. + +{{< scss-docs name="gray-color-variables" file="scss/_variables.scss" >}} + +Variables for setting `background-color` in `.bg-*-subtle` utilities in light and dark mode: + +{{< scss-docs name="theme-bg-subtle-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-bg-subtle-dark-variables" file="scss/_variables-dark.scss" >}} + +### Sass maps + +Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more. + +{{< scss-docs name="theme-colors-map" file="scss/_variables.scss" >}} + +Grayscale colors are also available as a Sass map. **This map is not used to generate any utilities.** + +{{< scss-docs name="gray-colors-map" file="scss/_variables.scss" >}} + +RGB colors are generated from a separate Sass map: + +{{< scss-docs name="theme-colors-rgb" file="scss/_maps.scss" >}} + +Background color opacities build on that with their own map that's consumed by the utilities API: + +{{< scss-docs name="utilities-bg-colors" file="scss/_maps.scss" >}} + +Color mode background colors are also available as a Sass map: + +{{< scss-docs name="theme-bg-subtle-map" file="scss/_maps.scss" >}} + +{{< scss-docs name="theme-bg-subtle-dark-map" file="scss/_maps.scss" >}} + +### Sass mixins + +**No mixins are used to generate our background utilities**, but we do have some additional mixins for other situations where you'd like to create your own gradients. + +{{< scss-docs name="gradient-bg-mixin" file="scss/mixins/_gradients.scss" >}} + +{{< scss-docs name="gradient-mixins" file="scss/mixins/_gradients.scss" >}} + +### Sass utilities API + +Background utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-bg-color" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/borders.md b/site/content/docs/5.3/utilities/borders.md new file mode 100644 index 0000000..b4fa2f4 --- /dev/null +++ b/site/content/docs/5.3/utilities/borders.md @@ -0,0 +1,194 @@ +--- +layout: docs +title: Borders +description: Use border utilities to quickly style the border and border-radius of an element. Great for images, buttons, or any other element. +group: utilities +toc: true +--- + +## Border + +Use border utilities to add or remove an element's borders. Choose from all borders or one at a time. + +### Additive + +Add borders to custom elements: + +{{< example class="bd-example-border-utils" >}} + + + + + +{{< /example >}} + +### Subtractive + +Or remove borders: + +{{< example class="bd-example-border-utils" >}} + + + + + +{{< /example >}} + +## Color + +{{< callout info >}} +Border utilities like `.border-*` that generated from our original `$theme-colors` Sass map don't yet respond to color modes, however, any `.border-*-subtle` utility will. This will be resolved in v6. +{{< /callout >}} + +Change the border color using utilities built on our theme colors. + +{{< example class="bd-example-border-utils" >}} +{{< border.inline >}} +{{- range (index $.Site.Data "theme-colors") }} + + +{{- end -}} +{{< /border.inline >}} + + +{{< /example >}} + +Or modify the default `border-color` of a component: + +{{< example >}} +
+ + +
+ +
+ Dangerous heading +
+ +
+ Changing border color and width +
+{{< /example >}} + +## Opacity + +{{< added-in "5.2.0" >}} + +Bootstrap `border-{color}` utilities are generated with Sass using CSS variables. This allows for real-time color changes without compilation and dynamic alpha transparency changes. + +### How it works + +Consider our default `.border-success` utility. + +```css +.border-success { + --bs-border-opacity: 1; + border-color: rgba(var(--bs-success-rgb), var(--bs-border-opacity)) !important; +} +``` + +We use an RGB version of our `--bs-success` (with the value of `25, 135, 84`) CSS variable and attached a second CSS variable, `--bs-border-opacity`, for the alpha transparency (with a default value `1` thanks to a local CSS variable). That means anytime you use `.border-success` now, your computed `color` value is `rgba(25, 135, 84, 1)`. The local CSS variable inside each `.border-*` class avoids inheritance issues so nested instances of the utilities don't automatically have a modified alpha transparency. + +### Example + +To change that opacity, override `--bs-border-opacity` via custom styles or inline styles. + +{{< example >}} +
This is default success border
+
This is 50% opacity success border
+{{< /example >}} + +Or, choose from any of the `.border-opacity` utilities: + +{{< example >}} +
This is default success border
+
This is 75% opacity success border
+
This is 50% opacity success border
+
This is 25% opacity success border
+
This is 10% opacity success border
+{{< /example >}} + +## Width + +{{< example class="bd-example-border-utils" >}} + + + + + +{{< /example >}} + +## Radius + +Add classes to an element to easily round its corners. + +{{< example class="bd-example-rounded-utils" >}} +{{< placeholder width="75" height="75" class="rounded" title="Example rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-top" title="Example top rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-end" title="Example right rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-bottom" title="Example bottom rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-start" title="Example left rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-circle" title="Completely round image" >}} +{{< placeholder width="150" height="75" class="rounded-pill" title="Rounded pill image" >}} +{{< /example >}} + +### Sizes + +Use the scaling classes for larger or smaller rounded corners. Sizes range from `0` to `5`, and can be configured by modifying the utilities API. + +{{< example class="bd-example-rounded-utils" >}} +{{< placeholder width="75" height="75" class="rounded-0" title="Example non-rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-1" title="Example small rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-2" title="Example default rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-3" title="Example large rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-4" title="Example larger rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-5" title="Example extra large rounded image" >}} +{{< /example >}} + +{{< example class="bd-example-rounded-utils" >}} +{{< placeholder width="75" height="75" class="rounded-bottom-1" title="Example small rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-start-2" title="Example default left rounded image" >}} +{{< placeholder width="75" height="75" class="rounded-end-circle" title="Example right completely round image" >}} +{{< placeholder width="75" height="75" class="rounded-start-pill" title="Example left rounded pill image" >}} +{{< placeholder width="75" height="75" class="rounded-5 rounded-top-0" title="Example extra large bottom rounded image" >}} +{{< /example >}} + +## CSS + +### Variables + +{{< added-in "5.2.0" >}} + +{{< scss-docs name="root-border-var" file="scss/_root.scss" >}} + +### Sass variables + +{{< scss-docs name="border-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="border-radius-variables" file="scss/_variables.scss" >}} + +Variables for setting `border-color` in `.border-*-subtle` utilities in light and dark mode: + +{{< scss-docs name="theme-border-subtle-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-border-subtle-dark-variables" file="scss/_variables-dark.scss" >}} + +### Sass maps + +Color mode adaptive border colors are also available as a Sass map: + +{{< scss-docs name="theme-border-subtle-map" file="scss/_maps.scss" >}} + +{{< scss-docs name="theme-border-subtle-dark-map" file="scss/_maps.scss" >}} + +### Sass mixins + +{{< scss-docs name="border-radius-mixins" file="scss/mixins/_border-radius.scss" >}} + +### Sass utilities API + +Border utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-borders" file="scss/_utilities.scss" >}} + +{{< scss-docs name="utils-border-radius" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/colors.md b/site/content/docs/5.3/utilities/colors.md new file mode 100644 index 0000000..775457d --- /dev/null +++ b/site/content/docs/5.3/utilities/colors.md @@ -0,0 +1,141 @@ +--- +layout: docs +title: Colors +description: Convey meaning through `color` with a handful of color utility classes. Includes support for styling links with hover states, too. +group: utilities +toc: true +--- + +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## Colors + +Colorize text with color utilities. If you want to colorize links, you can use the [`.link-*` helper classes]({{< docsref "/helpers/colored-links" >}}) which have `:hover` and `:focus` states. + +{{< callout info >}} +Color utilities like `.text-*` that generated from our original `$theme-colors` Sass map don't yet respond to color modes, however, any `.text-*-emphasis` utility will. This will be resolved in v6. +{{< /callout >}} + +{{< example >}} +{{< colors.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +

.text-{{ .name }}

+

.text-{{ .name }}-emphasis

+{{- end -}} +{{< /colors.inline >}} + +

.text-body

+

.text-body-emphasis

+

.text-body-secondary

+

.text-body-tertiary

+ +

.text-black

+

.text-white

+

.text-black-50

+

.text-white-50

+{{< /example >}} + +{{< callout warning >}} +**Deprecation:** With the addition of `.text-opacity-*` utilities and CSS variables for text utilities, `.text-black-50` and `.text-white-50` are deprecated as of v5.1.0. They'll be removed in v6.0.0. +{{< /callout >}} + +{{< callout warning >}} +**Deprecation:** With the addition of the expanded theme colors and variables, the `.text-muted` utility has been deprecated as of v5.3.0. Its default value has also been reassigned to the new `--bs-secondary-color` CSS variable to better support color modes. It will be removed in v6.0.0. +{{< /callout >}} + +## Opacity + +{{< added-in "5.1.0" >}} + +As of v5.1.0, text color utilities are generated with Sass using CSS variables. This allows for real-time color changes without compilation and dynamic alpha transparency changes. + +### How it works + +Consider our default `.text-primary` utility. + +```css +.text-primary { + --bs-text-opacity: 1; + color: rgba(var(--bs-primary-rgb), var(--bs-text-opacity)) !important; +} +``` + +We use an RGB version of our `--bs-primary` (with the value of `13, 110, 253`) CSS variable and attached a second CSS variable, `--bs-text-opacity`, for the alpha transparency (with a default value `1` thanks to a local CSS variable). That means anytime you use `.text-primary` now, your computed `color` value is `rgba(13, 110, 253, 1)`. The local CSS variable inside each `.text-*` class avoids inheritance issues so nested instances of the utilities don't automatically have a modified alpha transparency. + +### Example + +To change that opacity, override `--bs-text-opacity` via custom styles or inline styles. + +{{< example >}} +
This is default primary text
+
This is 50% opacity primary text
+{{< /example >}} + +Or, choose from any of the `.text-opacity` utilities: + +{{< example >}} +
This is default primary text
+
This is 75% opacity primary text
+
This is 50% opacity primary text
+
This is 25% opacity primary text
+{{< /example >}} + +## Specificity + +Sometimes contextual classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a `
` or more semantic element with the desired class. + +## CSS + +In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more. + +### Sass variables + +Most `color` utilities are generated by our theme colors, reassigned from our generic color palette variables. + +{{< scss-docs name="color-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-color-variables" file="scss/_variables.scss" >}} + +Grayscale colors are also available, but only a subset are used to generate any utilities. + +{{< scss-docs name="gray-color-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-text-map" file="scss/_maps.scss" >}} + +Variables for setting colors in `.text-*-emphasis` utilities in light and dark mode: + +{{< scss-docs name="theme-text-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-text-dark-variables" file="scss/_variables-dark.scss" >}} + +### Sass maps + +Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more. + +{{< scss-docs name="theme-colors-map" file="scss/_variables.scss" >}} + +Grayscale colors are also available as a Sass map. **This map is not used to generate any utilities.** + +{{< scss-docs name="gray-colors-map" file="scss/_variables.scss" >}} + +RGB colors are generated from a separate Sass map: + +{{< scss-docs name="theme-colors-rgb" file="scss/_maps.scss" >}} + +Color opacities build on that with their own map that's consumed by the utilities API: + +{{< scss-docs name="utilities-text-colors" file="scss/_maps.scss" >}} + +Color mode adaptive text colors are also available as a Sass map: + +{{< scss-docs name="theme-text-map" file="scss/_maps.scss" >}} + +{{< scss-docs name="theme-text-dark-map" file="scss/_maps.scss" >}} + +### Sass utilities API + +Color utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-color" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/display.md b/site/content/docs/5.3/utilities/display.md new file mode 100644 index 0000000..41541b9 --- /dev/null +++ b/site/content/docs/5.3/utilities/display.md @@ -0,0 +1,114 @@ +--- +layout: docs +title: Display property +description: Quickly and responsively toggle the display value of components and more with our display utilities. Includes support for some of the more common values, as well as some extras for controlling display when printing. +group: utilities +toc: true +--- + +## How it works + +Change the value of the [`display` property](https://developer.mozilla.org/en-US/docs/Web/CSS/display) with our responsive display utility classes. We purposely support only a subset of all possible values for `display`. Classes can be combined for various effects as you need. + +## Notation + +Display utility classes that apply to all [breakpoints]({{< docsref "/layout/breakpoints" >}}), from `xs` to `xxl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0;` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation. + +As such, the classes are named using the format: + +- `.d-{value}` for `xs` +- `.d-{breakpoint}-{value}` for `sm`, `md`, `lg`, `xl`, and `xxl`. + +Where *value* is one of: + +- `none` +- `inline` +- `inline-block` +- `block` +- `grid` +- `inline-grid` +- `table` +- `table-cell` +- `table-row` +- `flex` +- `inline-flex` + +The display values can be altered by changing the `display` values defined in `$utilities` and recompiling the SCSS. + +The media queries affect screen widths with the given breakpoint *or larger*. For example, `.d-lg-none` sets `display: none;` on `lg`, `xl`, and `xxl` screens. + +## Examples + +{{< example >}} +
d-inline
+
d-inline
+{{< /example >}} + +{{< example >}} +d-block +d-block +{{< /example >}} + +## Hiding elements + +For faster mobile-friendly development, use responsive display classes for showing and hiding elements by device. Avoid creating entirely different versions of the same site, instead hide elements responsively for each screen size. + +To hide elements simply use the `.d-none` class or one of the `.d-{sm,md,lg,xl,xxl}-none` classes for any responsive screen variation. + +To show an element only on a given interval of screen sizes you can combine one `.d-*-none` class with a `.d-*-*` class, for example `.d-none .d-md-block .d-xl-none .d-xxl-none` will hide the element for all screen sizes except on medium and large devices. + +{{< bs-table >}} +| Screen size | Class | +| --- | --- | +| Hidden on all | `.d-none` | +| Hidden only on xs | `.d-none .d-sm-block` | +| Hidden only on sm | `.d-sm-none .d-md-block` | +| Hidden only on md | `.d-md-none .d-lg-block` | +| Hidden only on lg | `.d-lg-none .d-xl-block` | +| Hidden only on xl | `.d-xl-none .d-xxl-block` | +| Hidden only on xxl | `.d-xxl-none` | +| Visible on all | `.d-block` | +| Visible only on xs | `.d-block .d-sm-none` | +| Visible only on sm | `.d-none .d-sm-block .d-md-none` | +| Visible only on md | `.d-none .d-md-block .d-lg-none` | +| Visible only on lg | `.d-none .d-lg-block .d-xl-none` | +| Visible only on xl | `.d-none .d-xl-block .d-xxl-none` | +| Visible only on xxl | `.d-none .d-xxl-block` | +{{< /bs-table >}} + +{{< example >}} +
hide on lg and wider screens
+
hide on screens smaller than lg
+{{< /example >}} + +## Display in print + +Change the `display` value of elements when printing with our print display utility classes. Includes support for the same `display` values as our responsive `.d-*` utilities. + +- `.d-print-none` +- `.d-print-inline` +- `.d-print-inline-block` +- `.d-print-block` +- `.d-print-grid` +- `.d-print-inline-grid` +- `.d-print-table` +- `.d-print-table-row` +- `.d-print-table-cell` +- `.d-print-flex` +- `.d-print-inline-flex` + +The print and display classes can be combined. + +{{< example >}} +
Screen Only (Hide on print only)
+
Print Only (Hide on screen only)
+
Hide up to large on screen, but always show on print
+{{< /example >}} + +## CSS + +### Sass utilities API + +Display utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-display" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/flex.md b/site/content/docs/5.3/utilities/flex.md new file mode 100644 index 0000000..d0a92e5 --- /dev/null +++ b/site/content/docs/5.3/utilities/flex.md @@ -0,0 +1,664 @@ +--- +layout: docs +title: Flex +description: Quickly manage the layout, alignment, and sizing of grid columns, navigation, components, and more with a full suite of responsive flexbox utilities. For more complex implementations, custom CSS may be necessary. +group: utilities +toc: true +--- + +## Enable flex behaviors + +Apply `display` utilities to create a flexbox container and transform **direct children elements** into flex items. Flex containers and items are able to be modified further with additional flex properties. + +{{< example class="bd-example-flex" >}} +
I'm a flexbox container!
+{{< /example >}} + +{{< example class="bd-example-flex" >}} +
I'm an inline flexbox container!
+{{< /example >}} + +Responsive variations also exist for `.d-flex` and `.d-inline-flex`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.d{{ .abbr }}-flex` +- `.d{{ .abbr }}-inline-flex` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Direction + +Set the direction of flex items in a flex container with direction utilities. In most cases you can omit the horizontal class here as the browser default is `row`. However, you may encounter situations where you needed to explicitly set this value (like responsive layouts). + +Use `.flex-row` to set a horizontal direction (the browser default), or `.flex-row-reverse` to start the horizontal direction from the opposite side. + +{{< example class="bd-example-flex" >}} +
+
Flex item 1
+
Flex item 2
+
Flex item 3
+
+
+
Flex item 1
+
Flex item 2
+
Flex item 3
+
+{{< /example >}} + +Use `.flex-column` to set a vertical direction, or `.flex-column-reverse` to start the vertical direction from the opposite side. + +{{< example class="bd-example-flex" >}} +
+
Flex item 1
+
Flex item 2
+
Flex item 3
+
+
+
Flex item 1
+
Flex item 2
+
Flex item 3
+
+{{< /example >}} + +Responsive variations also exist for `flex-direction`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.flex{{ .abbr }}-row` +- `.flex{{ .abbr }}-row-reverse` +- `.flex{{ .abbr }}-column` +- `.flex{{ .abbr }}-column-reverse` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Justify content + +Use `justify-content` utilities on flexbox containers to change the alignment of flex items on the main axis (the x-axis to start, y-axis if `flex-direction: column`). Choose from `start` (browser default), `end`, `center`, `between`, `around`, or `evenly`. + +
+
+
Justify
+
Content
+
Start
+
+
+
Justify
+
Content
+
End
+
+
+
Justify
+
Content
+
Center
+
+
+
Justify
+
Content
+
Between
+
+
+
Justify
+
Content
+
Around
+
+
+
Justify
+
Content
+
Evenly
+
+
+ +```html +
...
+
...
+
...
+
...
+
...
+
...
+``` + +Responsive variations also exist for `justify-content`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.justify-content{{ .abbr }}-start` +- `.justify-content{{ .abbr }}-end` +- `.justify-content{{ .abbr }}-center` +- `.justify-content{{ .abbr }}-between` +- `.justify-content{{ .abbr }}-around` +- `.justify-content{{ .abbr }}-evenly` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Align items + +Use `align-items` utilities on flexbox containers to change the alignment of flex items on the cross axis (the y-axis to start, x-axis if `flex-direction: column`). Choose from `start`, `end`, `center`, `baseline`, or `stretch` (browser default). + +
+
+
Flex item
+
Flex item
+
Flex item
+
+
+
Flex item
+
Flex item
+
Flex item
+
+
+
Flex item
+
Flex item
+
Flex item
+
+
+
Flex item
+
Flex item
+
Flex item
+
+
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
...
+
...
+
...
+
...
+
...
+``` + +Responsive variations also exist for `align-items`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.align-items{{ .abbr }}-start` +- `.align-items{{ .abbr }}-end` +- `.align-items{{ .abbr }}-center` +- `.align-items{{ .abbr }}-baseline` +- `.align-items{{ .abbr }}-stretch` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Align self + +Use `align-self` utilities on flexbox items to individually change their alignment on the cross axis (the y-axis to start, x-axis if `flex-direction: column`). Choose from the same options as `align-items`: `start`, `end`, `center`, `baseline`, or `stretch` (browser default). + +
+
+
Flex item
+
Aligned flex item
+
Flex item
+
+
+
Flex item
+
Aligned flex item
+
Flex item
+
+
+
Flex item
+
Aligned flex item
+
Flex item
+
+
+
Flex item
+
Aligned flex item
+
Flex item
+
+
+
Flex item
+
Aligned flex item
+
Flex item
+
+
+ +```html +
Aligned flex item
+
Aligned flex item
+
Aligned flex item
+
Aligned flex item
+
Aligned flex item
+``` + +Responsive variations also exist for `align-self`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.align-self{{ .abbr }}-start` +- `.align-self{{ .abbr }}-end` +- `.align-self{{ .abbr }}-center` +- `.align-self{{ .abbr }}-baseline` +- `.align-self{{ .abbr }}-stretch` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Fill + +Use the `.flex-fill` class on a series of sibling elements to force them into widths equal to their content (or equal widths if their content does not surpass their border-boxes) while taking up all available horizontal space. + +{{< example class="bd-example-flex" >}} +
+
Flex item with a lot of content
+
Flex item
+
Flex item
+
+{{< /example >}} + +Responsive variations also exist for `flex-fill`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.flex{{ .abbr }}-fill` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Grow and shrink + +Use `.flex-grow-*` utilities to toggle a flex item's ability to grow to fill available space. In the example below, the `.flex-grow-1` elements uses all available space it can, while allowing the remaining two flex items their necessary space. + +{{< example class="bd-example-flex" >}} +
+
Flex item
+
Flex item
+
Third flex item
+
+{{< /example >}} + +Use `.flex-shrink-*` utilities to toggle a flex item's ability to shrink if necessary. In the example below, the second flex item with `.flex-shrink-1` is forced to wrap its contents to a new line, "shrinking" to allow more space for the previous flex item with `.w-100`. + +{{< example class="bd-example-flex" >}} +
+
Flex item
+
Flex item
+
+{{< /example >}} + +Responsive variations also exist for `flex-grow` and `flex-shrink`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.flex{{ .abbr }}-{grow|shrink}-0` +- `.flex{{ .abbr }}-{grow|shrink}-1` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Auto margins + +Flexbox can do some pretty awesome things when you mix flex alignments with auto margins. Shown below are three examples of controlling flex items via auto margins: default (no auto margin), pushing two items to the right (`.me-auto`), and pushing two items to the left (`.ms-auto`). + +{{< example class="bd-example-flex" >}} +
+
Flex item
+
Flex item
+
Flex item
+
+ +
+
Flex item
+
Flex item
+
Flex item
+
+ +
+
Flex item
+
Flex item
+
Flex item
+
+{{< /example >}} + +### With align-items + +Vertically move one flex item to the top or bottom of a container by mixing `align-items`, `flex-direction: column`, and `margin-top: auto` or `margin-bottom: auto`. + +{{< example class="bd-example-flex" >}} +
+
Flex item
+
Flex item
+
Flex item
+
+ +
+
Flex item
+
Flex item
+
Flex item
+
+{{< /example >}} + +## Wrap + +Change how flex items wrap in a flex container. Choose from no wrapping at all (the browser default) with `.flex-nowrap`, wrapping with `.flex-wrap`, or reverse wrapping with `.flex-wrap-reverse`. + +
+
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
+ ... +
+``` + +
+
+
Flex item 1
+
Flex item 2
+
Flex item 3
+
Flex item 4
+
Flex item 5
+
Flex item 6
+
Flex item 7
+
Flex item 8
+
Flex item 9
+
Flex item 10
+
Flex item 11
+
Flex item 12
+
Flex item 13
+
Flex item 14
+
+
+ +```html +
+ ... +
+``` + +
+
+
Flex item 1
+
Flex item 2
+
Flex item 3
+
Flex item 4
+
Flex item 5
+
Flex item 6
+
Flex item 7
+
Flex item 8
+
Flex item 9
+
Flex item 10
+
Flex item 11
+
Flex item 12
+
Flex item 13
+
Flex item 14
+
+
+ +```html +
+ ... +
+``` + + +Responsive variations also exist for `flex-wrap`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.flex{{ .abbr }}-nowrap` +- `.flex{{ .abbr }}-wrap` +- `.flex{{ .abbr }}-wrap-reverse` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Order + +Change the _visual_ order of specific flex items with a handful of `order` utilities. We only provide options for making an item first or last, as well as a reset to use the DOM order. As `order` takes any integer value from 0 to 5, add custom CSS for any additional values needed. + +{{< example class="bd-example-flex" >}} +
+
First flex item
+
Second flex item
+
Third flex item
+
+{{< /example >}} + +Responsive variations also exist for `order`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $bp := $.Site.Data.breakpoints -}} +{{- range (seq 0 5) }} +- `.order{{ $bp.abbr }}-{{ . }}` +{{- end -}} +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +Additionally there are also responsive `.order-first` and `.order-last` classes that change the `order` of an element by applying `order: -1` and `order: 6`, respectively. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $bp := $.Site.Data.breakpoints -}} +{{- range (slice "first" "last") }} +- `.order{{ $bp.abbr }}-{{ . }}` +{{- end -}} +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Align content + +Use `align-content` utilities on flexbox containers to align flex items _together_ on the cross axis. Choose from `start` (browser default), `end`, `center`, `between`, `around`, or `stretch`. To demonstrate these utilities, we've enforced `flex-wrap: wrap` and increased the number of flex items. + +**Heads up!** This property has no effect on single rows of flex items. + +
+
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
+ ... +
+``` + +
+
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
...
+``` + +
+
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
...
+``` + +
+
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
...
+``` + +
+
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
...
+``` + +
+
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
Flex item
+
+
+ +```html +
...
+``` + +Responsive variations also exist for `align-content`. + +{{< markdown >}} +{{< flex.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.align-content{{ .abbr }}-start` +- `.align-content{{ .abbr }}-end` +- `.align-content{{ .abbr }}-center` +- `.align-content{{ .abbr }}-between` +- `.align-content{{ .abbr }}-around` +- `.align-content{{ .abbr }}-stretch` +{{- end -}} +{{< /flex.inline >}} +{{< /markdown >}} + +## Media object + +Looking to replicate the [media object component](https://getbootstrap.com/docs/4.6/components/media-object/) from Bootstrap 4? Recreate it in no time with a few flex utilities that allow even more flexibility and customization than before. + +{{< example >}} +
+
+ {{< placeholder width="100" height="100" color="#999" background="#e5e5e5" text="Image" >}} +
+
+ This is some content from a media component. You can replace this with any content and adjust it as needed. +
+
+{{< /example >}} + +And say you want to vertically center the content next to the image: + +{{< example >}} +
+
+ {{< placeholder width="100" height="100" color="#999" background="#e5e5e5" text="Image" >}} +
+
+ This is some content from a media component. You can replace this with any content and adjust it as needed. +
+
+{{< /example >}} + +## CSS + +### Sass utilities API + +Flexbox utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-flex" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/float.md b/site/content/docs/5.3/utilities/float.md new file mode 100644 index 0000000..a8d3efb --- /dev/null +++ b/site/content/docs/5.3/utilities/float.md @@ -0,0 +1,48 @@ +--- +layout: docs +title: Float +description: Toggle floats on any element, across any breakpoint, using our responsive float utilities. +group: utilities +toc: true +--- + +## Overview + +These utility classes float an element to the left or right, or disable floating, based on the current viewport size using the [CSS `float` property](https://developer.mozilla.org/en-US/docs/Web/CSS/float). `!important` is included to avoid specificity issues. These use the same viewport breakpoints as our grid system. Please be aware float utilities have no effect on flex items. + +{{< example >}} +
Float start on all viewport sizes

+
Float end on all viewport sizes

+
Don't float on all viewport sizes
+{{< /example >}} + +## Responsive + +Responsive variations also exist for each `float` value. + +{{< example >}} +
Float start on viewports sized SM (small) or wider

+
Float start on viewports sized MD (medium) or wider

+
Float start on viewports sized LG (large) or wider

+
Float start on viewports sized XL (extra-large) or wider

+{{< /example >}} + +Here are all the support classes: + +{{< markdown >}} +{{< float.inline >}} +{{- range $.Site.Data.breakpoints }} +- `.float{{ .abbr }}-start` +- `.float{{ .abbr }}-end` +- `.float{{ .abbr }}-none` +{{- end -}} +{{< /float.inline >}} +{{< /markdown >}} + +## CSS + +### Sass utilities API + +Float utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-float" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/interactions.md b/site/content/docs/5.3/utilities/interactions.md new file mode 100644 index 0000000..d602850 --- /dev/null +++ b/site/content/docs/5.3/utilities/interactions.md @@ -0,0 +1,42 @@ +--- +layout: docs +title: Interactions +description: Utility classes that change how users interact with contents of a website. +group: utilities +toc: false +--- + +## Text selection + +Change the way in which the content is selected when the user interacts with it. + +{{< example >}} +

This paragraph will be entirely selected when clicked by the user.

+

This paragraph has default select behavior.

+

This paragraph will not be selectable when clicked by the user.

+{{< /example >}} + +## Pointer events + +Bootstrap provides `.pe-none` and `.pe-auto` classes to prevent or add element interactions. + +{{< example >}} +

This link can not be clicked.

+

This link can be clicked (this is default behavior).

+

This link can not be clicked because the pointer-events property is inherited from its parent. However, this link has a pe-auto class and can be clicked.

+{{< /example >}} + +The `.pe-none` class (and the `pointer-events` CSS property it sets) only prevents interactions with a pointer (mouse, stylus, touch). Links and controls with `.pe-none` are, by default, still focusable and actionable for keyboard users. To ensure that they are completely neutralized even for keyboard users, you may need to add further attributes such as `tabindex="-1"` (to prevent them from receiving keyboard focus) and `aria-disabled="true"` (to convey the fact they are effectively disabled to assistive technologies), and possibly use JavaScript to completely prevent them from being actionable. + +If possible, the simpler solution is: + +- For form controls, add the `disabled` HTML attribute. +- For links, remove the `href` attribute, making it a non-interactive anchor or placeholder link. + +## CSS + +### Sass utilities API + +Interaction utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-interaction" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/link.md b/site/content/docs/5.3/utilities/link.md new file mode 100644 index 0000000..668af8c --- /dev/null +++ b/site/content/docs/5.3/utilities/link.md @@ -0,0 +1,105 @@ +--- +layout: docs +title: Link +description: Link utilities are used to stylize your anchors to adjust their color, opacity, underline offset, underline color, and more. +group: utilities +toc: true +added: 5.3 +--- + +## Link opacity + +Change the alpha opacity of the link `rgba()` color value with utilities. Please be aware that changes to a color's opacity can lead to links with [*insufficient* contrast]({{< docsref "getting-started/accessibility#color-contrast" >}}). + +{{< example >}} +

Link opacity 10

+

Link opacity 25

+

Link opacity 50

+

Link opacity 75

+

Link opacity 100

+{{< /example >}} + +You can even change the opacity level on hover. + +{{< example >}} +

Link hover opacity 10

+

Link hover opacity 25

+

Link hover opacity 50

+

Link hover opacity 75

+

Link hover opacity 100

+{{< /example >}} + +## Link underlines + +### Underline color + +Change the underline's color independent of the link text color. + +{{< example >}} +{{< link-underline-colors.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +

{{ .name | title }} underline

+{{- end -}} +{{< /link-underline-colors.inline >}} +{{< /example >}} + +### Underline offset + +Change the underline's distance from your text. Offset is set in `em` units to automatically scale with the element's current `font-size`. + +{{< example >}} +

Default link

+

Offset 1 link

+

Offset 2 link

+

Offset 3 link

+{{< /example >}} + +### Underline opacity + +Change the underline's opacity. Requires adding `.link-underline` to first set an `rgba()` color we use to then modify the alpha opacity. + +{{< example >}} +

Underline opacity 0

+

Underline opacity 10

+

Underline opacity 25

+

Underline opacity 50

+

Underline opacity 75

+

Underline opacity 100

+{{< /example >}} + +### Hover variants + +Just like the `.link-opacity-*-hover` utilities, `.link-offset` and `.link-underline-opacity` utilities include `:hover` variants by default. Mix and match to create unique link styles. + +{{< example >}} + + Underline opacity 0 + +{{< /example >}} + +## Colored links + +[Colored link helpers]({{< docsref "/helpers/colored-links/" >}}) have been updated to pair with our link utilities. Use the new utilities to modify the link opacity, underline opacity, and underline offset. + +{{< example >}} +{{< colored-links.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +

{{ .name | title }} link

+{{- end -}} +{{< /colored-links.inline >}} +

Emphasis link

+{{< /example >}} + +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## CSS + +In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more. + +### Sass utilities API + +Link utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-links" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/5.3/utilities/object-fit.md b/site/content/docs/5.3/utilities/object-fit.md new file mode 100644 index 0000000..babc70a --- /dev/null +++ b/site/content/docs/5.3/utilities/object-fit.md @@ -0,0 +1,63 @@ +--- +layout: docs +title: Object fit +description: Use the object fit utilities to modify how the content of a [replaced element](https://developer.mozilla.org/en-US/docs/Web/CSS/Replaced_element), such as an `` or `