Add new link utilities, icon link helper, and update colored link helpers (#37762)

* Add new link utilities, update colored link helpers

* Remove commented out code

* Fixes

* Remove examples changes

* Fixes and copy

* Fix icon-link instances on homepage

* Bump bundlewatch

* Fix node-sass issue for rgba() function bug

* More bundlewatch

* One more time after merge

* Add callout for a11y

* Hover and focus-visible

* Add a11y callouts

* Remove duplicate for now

* More code review feedback
This commit is contained in:
Mark Otto 2023-01-03 22:23:46 -08:00 committed by GitHub
parent 89f9ffc212
commit d70b5db2e0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
21 changed files with 305 additions and 62 deletions

View File

@ -18,19 +18,19 @@
},
{
"path": "./dist/css/bootstrap-utilities.css",
"maxSize": "10.75 kB"
"maxSize": "11.5 kB"
},
{
"path": "./dist/css/bootstrap-utilities.min.css",
"maxSize": "10.0 kB"
"maxSize": "10.75 kB"
},
{
"path": "./dist/css/bootstrap.css",
"maxSize": "31.5 kB"
"maxSize": "32.0 kB"
},
{
"path": "./dist/css/bootstrap.min.css",
"maxSize": "29.5 kB"
"maxSize": "30.0 kB"
},
{
"path": "./dist/js/bootstrap.bundle.js",

View File

@ -2,6 +2,7 @@
@import "helpers/color-bg";
@import "helpers/colored-links";
@import "helpers/focus-ring";
@import "helpers/icon-link";
@import "helpers/ratio";
@import "helpers/position";
@import "helpers/stacks";

View File

@ -116,6 +116,8 @@ $utilities-border-subtle: (
) !default;
// scss-docs-end utilities-border-colors
$utilities-links-underline: map-loop($utilities-colors, rgba-css-var, "$key", "link-underline") !default;
$negative-spacers: if($enable-negative-margins, negativify-map($spacers), null) !default;
$gutters: $spacers !default;

View File

@ -609,6 +609,56 @@ $utilities: map-merge(
values: $utilities-text-emphasis-colors
),
// scss-docs-end utils-color
// scss-docs-start utils-links
"link-opacity": (
css-var: true,
class: link-opacity,
state: hover,
values: (
10: .1,
25: .25,
50: .5,
75: .75,
100: 1
)
),
"link-offset": (
property: text-underline-offset,
class: link-offset,
state: hover,
values: (
1: .125em,
2: .25em,
3: .375em,
)
),
"link-underline": (
// css-var: true,
property: text-decoration-color,
class: link-underline,
local-vars: (
"link-underline-opacity": 1
),
values: map-merge(
$utilities-links-underline,
(
null: rgba(var(--#{$prefix}link-color-rgb), var(--#{$prefix}link-underline-opacity, 1)),
)
)
),
"link-underline-opacity": (
css-var: true,
class: link-underline-opacity,
state: hover,
values: (
10: .1,
25: .25,
50: .5,
75: .75,
100: 1
),
),
// scss-docs-end utils-links
// scss-docs-start utils-bg-color
"background-color": (
property: background-color,

View File

@ -1,11 +1,17 @@
// stylelint-disable function-name-case
// All-caps `RGBA()` function used because of this Sass bug: https://github.com/sass/node-sass/issues/2251
@each $color, $value in $theme-colors {
.link-#{$color} {
color: $value if($enable-important-utilities, !important, null);
--#{$prefix}link-color-rgb: #{to-rgb($value)};
text-decoration-color: RGBA(to-rgb($value), var(--#{$prefix}link-underline-opacity, 1));
@if $link-shade-percentage != 0 {
&:hover,
&:focus {
color: if(color-contrast($value) == $color-contrast-light, shade-color($value, $link-shade-percentage), tint-color($value, $link-shade-percentage)) if($enable-important-utilities, !important, null);
$hover-color: if(color-contrast($value) == $color-contrast-light, shade-color($value, $link-shade-percentage), tint-color($value, $link-shade-percentage));
--#{$prefix}link-color-rgb: #{to-rgb($hover-color)};
text-decoration-color: RGBA(to-rgb($hover-color), var(--#{$prefix}link-underline-opacity, 1));
}
}
}

View File

@ -0,0 +1,24 @@
.icon-link {
display: inline-flex;
gap: .375rem;
align-items: center;
text-decoration-color: rgba(var(--#{$prefix}link-color-rgb), var(--#{$prefix}link-opacity, .5));
text-underline-offset: .5rem;
backface-visibility: hidden;
> .bi {
flex-shrink: 0;
width: 1em;
height: 1em;
@include transition(.2s ease-in-out transform);
}
}
.icon-link-hover {
&:hover,
&:focus-visible {
> .bi {
transform: var(--#{$prefix}icon-link-transform, translate3d(.25em, 0, 0));
}
}
}

View File

@ -124,26 +124,6 @@
fill: currentcolor;
}
.icon-link {
display: flex;
align-items: center;
text-decoration-color: rgba($primary, .5);
text-underline-offset: .5rem;
backface-visibility: hidden;
.bi {
width: 1.5em;
height: 1.5em;
transition: .2s ease-in-out transform; // stylelint-disable-line property-disallowed-list
}
&:hover {
.bi {
transform: translate3d(5px, 0, 0);
}
}
}
.border-lg-start {
@include media-breakpoint-up(lg) {
border-left: var(--bs-border-width) solid var(--bs-border-color);

View File

@ -4,16 +4,6 @@
border-radius: .75rem;
}
.icon-link > .bi {
margin-top: .125rem;
margin-left: .125rem;
fill: currentcolor;
transition: transform .25s ease-in-out;
}
.icon-link:hover > .bi {
transform: translate(.25rem);
}
.icon-square {
width: 3rem;
height: 3rem;

View File

@ -76,9 +76,9 @@ body_class: ""
</div>
<h3 class="fs-2">Featured title</h3>
<p>Paragraph of text beneath the heading to explain the heading. We'll add onto it with another sentence and probably just keep going until we run out of words.</p>
<a href="#" class="icon-link d-inline-flex align-items-center">
<a href="#" class="icon-link">
Call to action
<svg class="bi" width="1em" height="1em"><use xlink:href="#chevron-right"/></svg>
<svg class="bi"><use xlink:href="#chevron-right"/></svg>
</a>
</div>
<div class="feature col">
@ -87,9 +87,9 @@ body_class: ""
</div>
<h3 class="fs-2">Featured title</h3>
<p>Paragraph of text beneath the heading to explain the heading. We'll add onto it with another sentence and probably just keep going until we run out of words.</p>
<a href="#" class="icon-link d-inline-flex align-items-center">
<a href="#" class="icon-link">
Call to action
<svg class="bi" width="1em" height="1em"><use xlink:href="#chevron-right"/></svg>
<svg class="bi"><use xlink:href="#chevron-right"/></svg>
</a>
</div>
<div class="feature col">
@ -98,9 +98,9 @@ body_class: ""
</div>
<h3 class="fs-2">Featured title</h3>
<p>Paragraph of text beneath the heading to explain the heading. We'll add onto it with another sentence and probably just keep going until we run out of words.</p>
<a href="#" class="icon-link d-inline-flex align-items-center">
<a href="#" class="icon-link">
Call to action
<svg class="bi" width="1em" height="1em"><use xlink:href="#chevron-right"/></svg>
<svg class="bi"><use xlink:href="#chevron-right"/></svg>
</a>
</div>
</div>

View File

@ -3,19 +3,35 @@ layout: docs
title: Colored links
description: Colored links with hover states
group: helpers
toc: false
toc: true
---
You can use the `.link-*` classes to colorize links. Unlike the [`.text-*` classes]({{< docsref "/utilities/colors" >}}), these classes have a `:hover` and `:focus` state.
## Link colors
You can use the `.link-*` classes to colorize links. Unlike the [`.text-*` classes]({{< docsref "/utilities/colors" >}}), these classes have a `:hover` and `:focus` state. 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.
{{< example >}}
{{< colored-links.inline >}}
{{- range (index $.Site.Data "theme-colors") }}
<a href="#" class="link-{{ .name }}">{{ .name | title }} link</a>
<p><a href="#" class="link-{{ .name }}">{{ .name | title }} link</a></p>
{{- 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.
{{< partial "callouts/warning-color-assistive-technologies.md" >}}
{{< /callout >}}
## Link utilities
{{< added-in "5.3.0" >}}
Colored links can also be modified by our [link utilities]({{< docsref "/utilities/link/" >}}).
{{< example >}}
{{< colored-links.inline >}}
{{- range (index $.Site.Data "theme-colors") }}
<p><a href="#" class="link-{{ .name }} link-offset-2 link-underline-opacity-25 link-underline-opacity-100-hover">{{ .name | title }} link</a></p>
{{- end -}}
{{< /colored-links.inline >}}
{{< /example >}}

View File

@ -0,0 +1,66 @@
---
layout: docs
title: Icon link
description: Quickly create stylized hyperlinks with Bootstrap Icons or other icons.
group: helpers
aliases: "/docs/5.3/icon-link/"
toc: true
added: 5.3
---
The icon link helper component modifies our default link styles to enhance their appearance and quickly align any pairing of icon and text. Alignment is set via inline flexbox styling and a default `gap` value. We stylize the underline with a custom offset and color. Icons are automatically sized to `1em` to best match their associated text's `font-size`.
Icon links assume [Bootstrap Icons](https://icons.getbootstrap.com) are being used, but you can use any icon or image you like.
{{< callout >}}
Icons used here are likely to be purely decorative, which means they should be hidden from assistive technologies using `aria-hidden="true"`, as we've done in our examples. For icons that are more than decorative, provide an appropriate text alternative via `alt` for `<img>` elements `role="img"` and `aria-label` for SVGs.
{{< /callout >}}
## Example
Take a regular `<a>` element, add `.icon-link`, and insert an icon on either the left or right of your link text. The icon is automatically sized, placed, and colored.
{{< example >}}
<a class="icon-link" href="#">
<svg class="bi" aria-hidden="true"><use xlink:href="#box-seam"></use></svg>
Icon link
</a>
{{< /example >}}
{{< example >}}
<a class="icon-link" href="#">
Icon link
<svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
</a>
{{< /example >}}
## Style on hover
Add `.icon-link-hover` to move the icon to the right on hover.
{{< example >}}
<a class="icon-link icon-link-hover" href="#">
Icon link
<svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
</a>
{{< /example >}}
Customize the hover `transform` by overriding the `--bs-icon-link-transform` CSS variable:
{{< example >}}
<a class="icon-link icon-link-hover" style="--bs-icon-link-transform: translate3d(0, -.125rem, 0);" href="#">
<svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"></use></svg>
Icon link
</a>
{{< /example >}}
## Pairs with link utilities
Modify icon links with any of [our link utilities]({{< docsref "/utilities/link/" >}}) for modifying underline color and offset.
{{< example >}}
<a class="icon-link icon-link-hover link-success link-underline-success link-underline-opacity-25" href="#">
Icon link
<svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
</a>
{{< /example >}}

View File

@ -0,0 +1,103 @@
---
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 >}}
<p><a class="link-opacity-10" href="#">Link opacity 10</a></p>
<p><a class="link-opacity-25" href="#">Link opacity 25</a></p>
<p><a class="link-opacity-50" href="#">Link opacity 50</a></p>
<p><a class="link-opacity-75" href="#">Link opacity 75</a></p>
<p><a class="link-opacity-100" href="#">Link opacity 100</a></p>
{{< /example >}}
You can even change the opacity level on hover.
{{< example >}}
<p><a class="link-opacity-10-hover" href="#">Link hover opacity 10</a></p>
<p><a class="link-opacity-25-hover" href="#">Link hover opacity 25</a></p>
<p><a class="link-opacity-50-hover" href="#">Link hover opacity 50</a></p>
<p><a class="link-opacity-75-hover" href="#">Link hover opacity 75</a></p>
<p><a class="link-opacity-100-hover" href="#">Link hover opacity 100</a></p>
{{< /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") }}
<p><a href="#" class="link-underline-{{ .name }}">{{ .name | title }} underline</a></p>
{{- 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 >}}
<p><a href="#">Default link</a></p>
<p><a class="link-offset-1" href="#">Offset 1 link</a></p>
<p><a class="link-offset-2" href="#">Offset 2 link</a></p>
<p><a class="link-offset-3" href="#">Offset 3 link</a></p>
{{< /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 >}}
<p><a class="link-offset-2 link-underline link-underline-opacity-10" href="#">Underline opacity 10</a></p>
<p><a class="link-offset-2 link-underline link-underline-opacity-25" href="#">Underline opacity 25</a></p>
<p><a class="link-offset-2 link-underline link-underline-opacity-50" href="#">Underline opacity 50</a></p>
<p><a class="link-offset-2 link-underline link-underline-opacity-75" href="#">Underline opacity 75</a></p>
<p><a class="link-offset-2 link-underline link-underline-opacity-100" href="#">Underline opacity 100</a></p>
{{< /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 >}}
<a class="link-offset-2 link-offset-3-hover link-underline link-underline-opacity-25 link-underline-opacity-75-hover" href="#">
Underline opacity 10
</a>
{{< /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") }}
<p><a href="#" class="link-{{ .name }} link-offset-2 link-underline-opacity-25 link-underline-opacity-100-hover">{{ .name | title }} link</a></p>
{{- end -}}
{{< /colored-links.inline >}}
{{< /example >}}
{{< callout info >}}
{{< partial "callouts/warning-color-assistive-technologies.md" >}}
{{< /callout >}}
## Sass
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.
### 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" >}}

View File

@ -105,6 +105,7 @@
- title: Color & background
- title: Colored links
- title: Focus ring
- title: Icon link
- title: Position
- title: Ratio
- title: Stacks
@ -125,6 +126,7 @@
- title: Flex
- title: Float
- title: Interactions
- title: Link
- title: Object fit
- title: Opacity
- title: Overflow

View File

@ -53,9 +53,9 @@
</ul>
`) "html" "" }}
<p class="d-flex justify-content-start mb-md-0">
<a href="/docs/{{ .Site.Params.docs_version }}/examples#snippets" class="icon-link fw-semibold">
<a href="/docs/{{ .Site.Params.docs_version }}/examples#snippets" class="icon-link icon-link-hover fw-semibold">
Explore customized components
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</div>
@ -78,9 +78,9 @@ $utilities: map-merge(
`) "scss" "" }}
<p class="d-flex justify-content-start mb-md-0">
<a href="/docs/{{ .Site.Params.docs_version }}/utilities/api/" class="icon-link fw-semibold mb-3">
<a href="/docs/{{ .Site.Params.docs_version }}/utilities/api/" class="icon-link icon-link-hover fw-semibold mb-3">
Explore the utility API
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</div>

View File

@ -8,9 +8,9 @@
Bootstrap 5 is evolving with each release to better utilize CSS variables for global theme styles, individual components, and even utilities. We provide dozens of variables for colors, font styles, and more at a <code>:root</code> level for use anywhere. On components and utilities, CSS variables are scoped to the relevant class and can easily be modified.
</p>
<p class="d-flex align-items-start flex-column lead fw-normal mb-0">
<a href="/docs/{{ .Site.Params.docs_version }}/customize/css-variables/" class="icon-link fw-semibold mb-3">
<a href="/docs/{{ .Site.Params.docs_version }}/customize/css-variables/" class="icon-link icon-link-hover fw-semibold mb-3">
Learn more about CSS variables
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</div>

View File

@ -7,9 +7,9 @@
Bootstrap utilizes Sass for a modular and customizable architecture. Import only the components you need, enable global options like gradients and shadows, and write your own CSS with our variables, maps, functions, and mixins.
</p>
<p class="d-flex justify-content-start lead fw-normal">
<a href="/docs/{{ .Site.Params.docs_version }}/customize/overview/" class="icon-link fw-semibold">
<a href="/docs/{{ .Site.Params.docs_version }}/customize/overview/" class="icon-link icon-link-hover fw-semibold">
Learn more about customizing
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</section>

View File

@ -7,9 +7,9 @@
Jump right into building with Bootstrap—use the CDN, install it via package manager, or download the source code.
</p>
<p class="d-flex justify-content-md-start justify-content-md-center lead fw-normal">
<a href="/docs/{{ .Site.Params.docs_version }}/getting-started/download/" class="icon-link fw-semibold justify-content-center ps-md-4">
<a href="/docs/{{ .Site.Params.docs_version }}/getting-started/download/" class="icon-link icon-link-hover fw-semibold ps-md-4">
Read installation docs
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</div>

View File

@ -8,9 +8,9 @@
<a href="{{ .Site.Params.icons }}">Bootstrap Icons</a> is an open source SVG icon library featuring over 1,800 glyphs, with more added every release. They're designed to work in any project, whether you use Bootstrap itself or not. Use them as SVGs or icon fonts—both options give you vector scaling and easy customization via CSS.
</p>
<p class="d-flex justify-content-start lead fw-normal mb-md-0">
<a href="{{ .Site.Params.icons }}" class="icon-link fw-semibold">
<a href="{{ .Site.Params.icons }}" class="icon-link icon-link-hover fw-semibold">
Get Bootstrap Icons
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</div>

View File

@ -8,9 +8,9 @@
Add toggleable hidden elements, modals and offcanvas menus, popovers and tooltips, and so much more—all without jQuery. Bootstrap's JavaScript is HTML-first, meaning most plugins are added with <code>data</code> attributes in your HTML. Need more control? Include individual plugins programmatically.
</p>
<p class="d-flex justify-content-start lead fw-normal mb-md-0">
<a href="/docs/{{ .Site.Params.docs_version }}/getting-started/javascript/" class="icon-link fw-semibold">
<a href="/docs/{{ .Site.Params.docs_version }}/getting-started/javascript/" class="icon-link icon-link-hover fw-semibold">
Learn more about Bootstrap JavaScript
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</div>

View File

@ -8,9 +8,9 @@
Take Bootstrap to the next level with premium themes from the <a href="{{ .Site.Params.themes }}">official Bootstrap Themes marketplace</a>. Themes are built on Bootstrap as their own extended frameworks, rich with new components and plugins, documentation, and powerful build tools.
</p>
<p class="d-flex justify-content-start lead fw-normal mb-md-0">
<a href="{{ .Site.Params.themes }}" class="icon-link fw-semibold">
<a href="{{ .Site.Params.themes }}" class="icon-link icon-link-hover fw-semibold">
Browse Bootstrap Themes
<svg class="bi"><use xlink:href="#arrow-right-short"></use></svg>
<svg class="bi"><use xlink:href="#arrow-right"></use></svg>
</a>
</p>
</div>

View File

@ -1,4 +1,7 @@
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="arrow-right" viewBox="0 0 16 16">
<path fill-rule="evenodd" d="M1 8a.5.5 0 0 1 .5-.5h11.793l-3.147-3.146a.5.5 0 0 1 .708-.708l4 4a.5.5 0 0 1 0 .708l-4 4a.5.5 0 0 1-.708-.708L13.293 8.5H1.5A.5.5 0 0 1 1 8z"/>
</symbol>
<symbol id="arrow-right-short" viewBox="0 0 16 16">
<path fill-rule="evenodd" d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"/>
</symbol>

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB