diff options
Diffstat (limited to 'site/content/docs/5.2/helpers')
| -rw-r--r-- | site/content/docs/5.2/helpers/clearfix.md | 36 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/color-background.md | 52 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/colored-links.md | 21 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/position.md | 63 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/ratio.md | 81 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/stacks.md | 85 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/stretched-link.md | 74 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/text-truncation.md | 23 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/vertical-rule.md | 45 | ||||
| -rw-r--r-- | site/content/docs/5.2/helpers/visually-hidden.md | 29 |
10 files changed, 509 insertions, 0 deletions
diff --git a/site/content/docs/5.2/helpers/clearfix.md b/site/content/docs/5.2/helpers/clearfix.md new file mode 100644 index 0000000..c888610 --- /dev/null +++ b/site/content/docs/5.2/helpers/clearfix.md @@ -0,0 +1,36 @@ +--- +layout: docs +title: Clearfix +description: Quickly and easily clear floated content within a container by adding a clearfix utility. +group: helpers +aliases: "/docs/5.2/helpers/" +--- + +Easily clear `float`s by adding `.clearfix` **to the parent element**. Can also be used as a mixin. + +Use in HTML: + +```html +<div class="clearfix">...</div> +``` + +The mixin source code: + +{{< scss-docs name="clearfix" file="scss/mixins/_clearfix.scss" >}} + +Use the mixin in SCSS: + +```scss +.element { + @include clearfix; +} +``` + +The following example shows how the clearfix can be used. Without the clearfix the wrapping div would not span around the buttons which would cause a broken layout. + +{{< example >}} +<div class="bg-info clearfix"> + <button type="button" class="btn btn-secondary float-start">Example Button floated left</button> + <button type="button" class="btn btn-secondary float-end">Example Button floated right</button> +</div> +{{< /example >}} diff --git a/site/content/docs/5.2/helpers/color-background.md b/site/content/docs/5.2/helpers/color-background.md new file mode 100644 index 0000000..c417484 --- /dev/null +++ b/site/content/docs/5.2/helpers/color-background.md @@ -0,0 +1,52 @@ +--- +layout: docs +title: Color & background +description: Set a background color with contrasting foreground color. +group: helpers +toc: true +added: "5.2" +--- + +## Overview + +{{< added-in "5.2.0" >}} + +Color and background helpers combine the power of our [`.text-*` utilities]({{< docsref "/utilities/colors" >}}) and [`.bg-*` utilities]({{< docsref "/utilities/background" >}}) in one class. Using our Sass `color-contrast()` function, we automatically determine a contrasting `color` for a particular `background-color`. + +{{< callout warning >}} +**Heads up!** There's currently no support for a CSS-native `color-contrast` function, so we use our own via Sass. This means that customizing our theme colors via CSS variables may cause color contrast issues with these utilities. +{{< /callout >}} + +{{< example >}} +{{< text-bg.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<div class="text-bg-{{ .name }} p-3">{{ .name | title }} with contrasting color</div> +{{- end -}} +{{< /text-bg.inline >}} +{{< /example >}} + +## With components + +Use them in place of combined `.text-*` and `.bg-*` classes, like on [badges]({{< docsref "/components/badge#background-colors" >}}): + +{{< example >}} +<span class="badge text-bg-primary">Primary</span> +<span class="badge text-bg-info">Info</span> +{{< /example >}} + +Or on [cards]({{< docsref "/components/card#background-and-color" >}}): + +{{< example >}} +<div class="card text-bg-primary mb-3" style="max-width: 18rem;"> + <div class="card-header">Header</div> + <div class="card-body"> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + </div> +</div> +<div class="card text-bg-info mb-3" style="max-width: 18rem;"> + <div class="card-header">Header</div> + <div class="card-body"> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + </div> +</div> +{{< /example >}} diff --git a/site/content/docs/5.2/helpers/colored-links.md b/site/content/docs/5.2/helpers/colored-links.md new file mode 100644 index 0000000..e940196 --- /dev/null +++ b/site/content/docs/5.2/helpers/colored-links.md @@ -0,0 +1,21 @@ +--- +layout: docs +title: Colored links +description: Colored links with hover states +group: helpers +toc: false +--- + +You can use the `.link-*` classes to colorize links. Unlike the [`.text-*` classes]({{< docsref "/utilities/colors" >}}), these classes have a `:hover` and `:focus` state. + +{{< example >}} +{{< colored-links.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +<a href="#" class="link-{{ .name }}">{{ .name | title }} link</a> +{{- end -}} +{{< /colored-links.inline >}} +{{< /example >}} + +{{< callout info >}} +Some of the link styles use a relatively light foreground color, and should only be used on a dark background in order to have sufficient contrast. +{{< /callout >}} diff --git a/site/content/docs/5.2/helpers/position.md b/site/content/docs/5.2/helpers/position.md new file mode 100644 index 0000000..b4e1f71 --- /dev/null +++ b/site/content/docs/5.2/helpers/position.md @@ -0,0 +1,63 @@ +--- +layout: docs +title: Position +description: Use these helpers for quickly configuring the position of an element. +group: helpers +toc: true +--- + +## Fixed top + +Position an element at the top of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add additional CSS. + +```html +<div class="fixed-top">...</div> +``` + +## Fixed bottom + +Position an element at the bottom of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add additional CSS. + +```html +<div class="fixed-bottom">...</div> +``` + +## Sticky top + +Position an element at the top of the viewport, from edge to edge, but only after you scroll past it. + +```html +<div class="sticky-top">...</div> +``` + +## Responsive sticky top + +Responsive variations also exist for `.sticky-top` utility. + +```html +<div class="sticky-sm-top">Stick to the top on viewports sized SM (small) or wider</div> +<div class="sticky-md-top">Stick to the top on viewports sized MD (medium) or wider</div> +<div class="sticky-lg-top">Stick to the top on viewports sized LG (large) or wider</div> +<div class="sticky-xl-top">Stick to the top on viewports sized XL (extra-large) or wider</div> +<div class="sticky-xxl-top">Stick to the top on viewports sized XXL (extra-extra-large) or wider</div> +``` + +## Sticky bottom + +Position an element at the bottom of the viewport, from edge to edge, but only after you scroll past it. + +```html +<div class="sticky-bottom">...</div> +``` + +## Responsive sticky bottom + +Responsive variations also exist for `.sticky-bottom` utility. + +```html +<div class="sticky-sm-bottom">Stick to the bottom on viewports sized SM (small) or wider</div> +<div class="sticky-md-bottom">Stick to the bottom on viewports sized MD (medium) or wider</div> +<div class="sticky-lg-bottom">Stick to the bottom on viewports sized LG (large) or wider</div> +<div class="sticky-xl-bottom">Stick to the bottom on viewports sized XL (extra-large) or wider</div> +<div class="sticky-xxl-bottom">Stick to the bottom on viewports sized XXL (extra-extra-large) or wider</div> +``` diff --git a/site/content/docs/5.2/helpers/ratio.md b/site/content/docs/5.2/helpers/ratio.md new file mode 100644 index 0000000..771bc07 --- /dev/null +++ b/site/content/docs/5.2/helpers/ratio.md @@ -0,0 +1,81 @@ +--- +layout: docs +title: Ratios +description: Use generated pseudo elements to make an element maintain the aspect ratio of your choosing. Perfect for responsively handling video or slideshow embeds based on the width of the parent. +group: helpers +toc: true +--- + +## About + +Use the ratio helper to manage the aspect ratios of external content like `<iframe>`s, `<embed>`s, `<video>`s, and `<object>`s. These helpers also can be used on any standard HTML child element (e.g., a `<div>` or `<img>`). Styles are applied from the parent `.ratio` class directly to the child. + +Aspect ratios are declared in a Sass map and included in each class via CSS variable, which also allows [custom aspect ratios](#custom-ratios). + +{{< callout info >}} +**Pro-Tip!** You don't need `frameborder="0"` on your `<iframe>`s as we override that for you in [Reboot]({{< docsref "/content/reboot" >}}). +{{< /callout >}} + +## Example + +Wrap any embed, like an `<iframe>`, in a parent element with `.ratio` and an aspect ratio class. The immediate child element is automatically sized thanks to our universal selector `.ratio > *`. + +{{< example >}} +<div class="ratio ratio-16x9"> + <iframe src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe> +</div> +{{< /example >}} + +## Aspect ratios + +Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided: + +{{< example class="bd-example-ratios" >}} +<div class="ratio ratio-1x1"> + <div>1x1</div> +</div> +<div class="ratio ratio-4x3"> + <div>4x3</div> +</div> +<div class="ratio ratio-16x9"> + <div>16x9</div> +</div> +<div class="ratio ratio-21x9"> + <div>21x9</div> +</div> +{{< /example >}} + +## Custom ratios + +Each `.ratio-*` class includes a CSS custom property (or CSS variable) in the selector. You can override this CSS variable to create custom aspect ratios on the fly with some quick math on your part. + +For example, to create a 2x1 aspect ratio, set `--bs-aspect-ratio: 50%` on the `.ratio`. + +{{< example class="bd-example-ratios" >}} +<div class="ratio" style="--bs-aspect-ratio: 50%;"> + <div>2x1</div> +</div> +{{< /example >}} + +This CSS variable makes it easy to modify the aspect ratio across breakpoints. The following is 4x3 to start, but changes to a custom 2x1 at the medium breakpoint. + +```scss +.ratio-4x3 { + @include media-breakpoint-up(md) { + --bs-aspect-ratio: 50%; // 2x1 + } +} +``` + +{{< example class="bd-example-ratios bd-example-ratios-breakpoint" >}} +<div class="ratio ratio-4x3"> + <div>4x3, then 2x1</div> +</div> +{{< /example >}} + + +## Sass map + +Within `_variables.scss`, you can change the aspect ratios you want to use. Here's our default `$ratio-aspect-ratios` map. Modify the map as you like and recompile your Sass to put them to use. + +{{< scss-docs name="aspect-ratios" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/helpers/stacks.md b/site/content/docs/5.2/helpers/stacks.md new file mode 100644 index 0000000..e1960c5 --- /dev/null +++ b/site/content/docs/5.2/helpers/stacks.md @@ -0,0 +1,85 @@ +--- +layout: docs +title: Stacks +description: Shorthand helpers that build on top of our flexbox utilities to make component layout faster and easier than ever. +group: helpers +toc: true +added: "5.1" +--- + +Stacks offer a shortcut for applying a number of flexbox properties to quickly and easily create layouts in Bootstrap. All credit for the concept and implementation goes to the open source [Pylon project](https://almonk.github.io/pylon/). + +{{< callout warning >}} +Heads up! Support for gap utilities with flexbox was recently added to Safari, so consider verifying your intended browser support. Grid layout should have no issues. [Read more](https://caniuse.com/flexbox-gap). +{{< /callout >}} + +## Vertical + +Use `.vstack` to create vertical layouts. Stacked items are full-width by default. Use `.gap-*` utilities to add space between items. + +{{< example >}} +<div class="vstack gap-3"> + <div class="bg-light border">First item</div> + <div class="bg-light border">Second item</div> + <div class="bg-light border">Third item</div> +</div> +{{< /example >}} + +## Horizontal + +Use `.hstack` for horizontal layouts. Stacked items are vertically centered by default and only take up their necessary width. Use `.gap-*` utilities to add space between items. + +{{< example >}} +<div class="hstack gap-3"> + <div class="bg-light border">First item</div> + <div class="bg-light border">Second item</div> + <div class="bg-light border">Third item</div> +</div> +{{< /example >}} + +Using horizontal margin utilities like `.ms-auto` as spacers: + +{{< example >}} +<div class="hstack gap-3"> + <div class="bg-light border">First item</div> + <div class="bg-light border ms-auto">Second item</div> + <div class="bg-light border">Third item</div> +</div> +{{< /example >}} + +And with [vertical rules]({{< docsref "/helpers/vertical-rule" >}}): + +{{< example >}} +<div class="hstack gap-3"> + <div class="bg-light border">First item</div> + <div class="bg-light border ms-auto">Second item</div> + <div class="vr"></div> + <div class="bg-light border">Third item</div> +</div> +{{< /example >}} + +## Examples + +Use `.vstack` to stack buttons and other elements: + +{{< example >}} +<div class="vstack gap-2 col-md-5 mx-auto"> + <button type="button" class="btn btn-secondary">Save changes</button> + <button type="button" class="btn btn-outline-secondary">Cancel</button> +</div> +{{< /example >}} + +Create an inline form with `.hstack`: + +{{< example >}} +<div class="hstack gap-3"> + <input class="form-control me-auto" type="text" placeholder="Add your item here..." aria-label="Add your item here..."> + <button type="button" class="btn btn-secondary">Submit</button> + <div class="vr"></div> + <button type="button" class="btn btn-outline-danger">Reset</button> +</div> +{{< /example >}} + +## Sass + +{{< scss-docs name="stacks" file="scss/helpers/_stacks.scss" >}} diff --git a/site/content/docs/5.2/helpers/stretched-link.md b/site/content/docs/5.2/helpers/stretched-link.md new file mode 100644 index 0000000..93bffeb --- /dev/null +++ b/site/content/docs/5.2/helpers/stretched-link.md @@ -0,0 +1,74 @@ +--- +layout: docs +title: Stretched link +description: Make any HTML element or Bootstrap component clickable by "stretching" a nested link via CSS. +group: helpers +--- + +Add `.stretched-link` to a link to make its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block) clickable via a `::after` pseudo element. In most cases, this means that an element with `position: relative;` that contains a link with the `.stretched-link` class is clickable. Please note given [how CSS `position` works](https://www.w3.org/TR/CSS21/visuren.html#propdef-position), `.stretched-link` cannot be mixed with most table elements. + +Cards have `position: relative` by default in Bootstrap, so in this case you can safely add the `.stretched-link` class to a link in the card without any other HTML changes. + +Multiple links and tap targets are not recommended with stretched links. However, some `position` and `z-index` styles can help should this be required. + +{{< example >}} +<div class="card" style="width: 18rem;"> + {{< placeholder width="100%" height="180" class="card-img-top" text="false" title="Card image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card with stretched link</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + <a href="#" class="btn btn-primary stretched-link">Go somewhere</a> + </div> +</div> +{{< /example >}} + +Most custom components do not have `position: relative` by default, so we need to add the `.position-relative` here to prevent the link from stretching outside the parent element. + +{{< example >}} +<div class="d-flex position-relative"> + {{< placeholder width="144" height="144" class="flex-shrink-0 me-3" text="false" title="Generic placeholder image" >}} + <div> + <h5 class="mt-0">Custom component with stretched link</h5> + <p>This is some placeholder content for the custom component. It is intended to mimic what some real-world content would look like, and we're using it here to give the component a bit of body and size.</p> + <a href="#" class="stretched-link">Go somewhere</a> + </div> +</div> +{{< /example >}} + +{{< example >}} +<div class="row g-0 bg-light position-relative"> + <div class="col-md-6 mb-md-0 p-md-4"> + {{< placeholder width="100%" height="200" class="w-100" text="false" title="Generic placeholder image" >}} + </div> + <div class="col-md-6 p-4 ps-md-0"> + <h5 class="mt-0">Columns with stretched link</h5> + <p>Another instance of placeholder content for this other custom component. It is intended to mimic what some real-world content would look like, and we're using it here to give the component a bit of body and size.</p> + <a href="#" class="stretched-link">Go somewhere</a> + </div> +</div> +{{< /example >}} + +## Identifying the containing block + +If the stretched link doesn't seem to work, the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block) will probably be the cause. The following CSS properties will make an element the containing block: + +- A `position` value other than `static` +- A `transform` or `perspective` value other than `none` +- A `will-change` value of `transform` or `perspective` +- A `filter` value other than `none` or a `will-change` value of `filter` (only works on Firefox) + +{{< example >}} +<div class="card" style="width: 18rem;"> + {{< placeholder width="100%" height="180" class="card-img-top" text="false" title="Card image cap" >}} + <div class="card-body"> + <h5 class="card-title">Card with stretched links</h5> + <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p> + <p class="card-text"> + <a href="#" class="stretched-link text-danger" style="position: relative;">Stretched link will not work here, because <code>position: relative</code> is added to the link</a> + </p> + <p class="card-text bg-light" style="transform: rotate(0);"> + This <a href="#" class="text-warning stretched-link">stretched link</a> will only be spread over the <code>p</code>-tag, because a transform is applied to it. + </p> + </div> +</div> +{{< /example >}} diff --git a/site/content/docs/5.2/helpers/text-truncation.md b/site/content/docs/5.2/helpers/text-truncation.md new file mode 100644 index 0000000..799f205 --- /dev/null +++ b/site/content/docs/5.2/helpers/text-truncation.md @@ -0,0 +1,23 @@ +--- +layout: docs +title: Text truncation +description: Truncate long strings of text with an ellipsis. +group: helpers +toc: false +--- + +For longer content, you can add a `.text-truncate` class to truncate the text with an ellipsis. **Requires `display: inline-block` or `display: block`.** + +{{< example >}} +<!-- Block level --> +<div class="row"> + <div class="col-2 text-truncate"> + This text is quite long, and will be truncated once displayed. + </div> +</div> + +<!-- Inline level --> +<span class="d-inline-block text-truncate" style="max-width: 150px;"> + This text is quite long, and will be truncated once displayed. +</span> +{{< /example >}} diff --git a/site/content/docs/5.2/helpers/vertical-rule.md b/site/content/docs/5.2/helpers/vertical-rule.md new file mode 100644 index 0000000..b734f61 --- /dev/null +++ b/site/content/docs/5.2/helpers/vertical-rule.md @@ -0,0 +1,45 @@ +--- +layout: docs +title: Vertical rule +description: Use the custom vertical rule helper to create vertical dividers like the `<hr>` element. +group: helpers +toc: true +added: "5.1" +--- + +## How it works + +Vertical rules are inspired by the `<hr>` element, allowing you to create vertical dividers in common layouts. They're styled just like `<hr>` elements: + +- They're `1px` wide +- They have `min-height` of `1em` +- Their color is set via `currentColor` and `opacity` + +Customize them with additional styles as needed. + +## Example + +{{< example >}} +<div class="vr"></div> +{{< /example >}} + +Vertical rules scale their height in flex layouts: + +{{< example >}} +<div class="d-flex" style="height: 200px;"> + <div class="vr"></div> +</div> +{{< /example >}} + +## With stacks + +They can also be used in [stacks]({{< docsref "/helpers/stacks" >}}): + +{{< example >}} +<div class="hstack gap-3"> + <div class="bg-light border">First item</div> + <div class="bg-light border ms-auto">Second item</div> + <div class="vr"></div> + <div class="bg-light border">Third item</div> +</div> +{{< /example >}} diff --git a/site/content/docs/5.2/helpers/visually-hidden.md b/site/content/docs/5.2/helpers/visually-hidden.md new file mode 100644 index 0000000..1124065 --- /dev/null +++ b/site/content/docs/5.2/helpers/visually-hidden.md @@ -0,0 +1,29 @@ +--- +layout: docs +title: Visually hidden +description: Use these helpers to visually hide elements but keep them accessible to assistive technologies. +group: helpers +aliases: "/docs/5.2/helpers/screen-readers/" +--- + +Visually hide an element while still allowing it to be exposed to assistive technologies (such as screen readers) with `.visually-hidden`. Use `.visually-hidden-focusable` to visually hide an element by default, but to display it when it's focused (e.g. by a keyboard-only user). `.visually-hidden-focusable` can also be applied to a container–thanks to `:focus-within`, the container will be displayed when any child element of the container receives focus. + +{{< example >}} +<h2 class="visually-hidden">Title for screen readers</h2> +<a class="visually-hidden-focusable" href="#content">Skip to main content</a> +<div class="visually-hidden-focusable">A container with a <a href="#">focusable element</a>.</div> +{{< /example >}} + +Both `visually-hidden` and `visually-hidden-focusable` can also be used as mixins. + +```scss +// Usage as a mixin + +.visually-hidden-title { + @include visually-hidden; +} + +.skip-navigation { + @include visually-hidden-focusable; +} +``` |