Guidance and suggestions for using icons library with OUDS Web.
On this page
You may use two types of icons in your projects, like in this documentation:
- Project icons: As part of an eco-design approach, the icons from the Sosh icons library are not included in OUDS Web by default. You must select the icons you need and import them, preferably into an SVG sprite file. See using icons section for more technical information about the ways to import icons.
- Component icons: Provided directly by OUDS Web, they are part of certain components, such as the breadcrumb separator or the list bullet. These icons are defined directly in our CSS stylesheet and integrated into OUDS Web.
Rendering
Icons are designed within a square layout to preserve consistency. Within this square, there exists a designated safety zone to guarantee that icons can be used in various sizes and contexts while maintaining alignment as intended by the designers. The dimensions of the icons encompass this safety zone, ensuring adaptability and consistency across diverse applications.
You can use the utility classes provided in the icons sizing utilities documentation to adjust the size of your icons according to your needs.
Usage
There are many ways to integrate icons in a web page, here are the most common ones, with their advantages and drawbacks.
| Method | Integration | Advantages | Drawbacks | Recommendation |
|---|---|---|---|---|
| SVG sprite | Bundled |
|
| Recommended for most use cases, for flexibility, performance and accessibility |
| Icon font | Bundled |
|
| Use only with many icons (>20) |
| CSS background image | Individual |
|
| Use via mask image in CSS pseudo-elements, can be related to a component |
| Inline SVG | Individual |
|
| One-time integration of a single icon |
| External SVG | Individual |
|
| One-time integration of a single-color icon |
SVG sprite
This technique is the preferred choice for flexibility, performance and accessibility.
With SVG sprites, you can benefit of the power of currentColor for easy coloring and theming.
Please note that if you experience a problem with a cropped SVG, we recommend using the .overflow-visible utility on the SVG to fix its rendering.
SVG sprite file example:
<svg xmlns="http://www.w3.org/2000/svg">
<symbol id="settings" fill="currentColor" viewBox="0 0 1000 1000">
<path d="..." fill-rule="evenodd"/>
</symbol>
<symbol id="trash" fill="currentColor" viewBox="0 0 1000 1000">
<path d="..." fill-rule="evenodd"/>
</symbol>
</svg>
SVG sprite usage:
<svg class="decorative-large-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#settings" />
</svg>
<svg class="decorative-large-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#trash" />
</svg>
To speed up loading, the SVG sprite file can be preloaded in the <head> of the page:
<link rel="preload" href="/path/to/your/sprite.svg" as="image" type="image/svg+xml" />
Icon font
Icon font is not the preferred solution. However, for websites needing more than 20 icons, you may consider using an icon font instead of an SVG sprite for eco-design reasons.
you can generate an icon font containing all your icons and use it like a classic font. Icons can be styled through CSS properties like font-size and color. Please keep in mind that adding or removing icons from the font afterward can be complicated.
<span class="si si-settings decorative-large-icon" aria-hidden="true"></span>
CSS background image
CSS background icons should be used when you can’t or don’t want to refer to an external image, or if you want to include the icon in a CSS ::before or ::after pseudo-element. Be aware that you cannot provide an alternative text for assistive technologies, so use it wisely.
Technically, you should use the mask-image property instead of background-image to benefit from the coloring and theming system, by setting background-color property to currentcolor. You can use the SVG code within your CSS (be sure to escape any characters with our internal escape-svg() function). When no dimensions are specified via width and height on the <svg>, the icon will fill the available space. Mask images can also be styled through CSS properties like width or height. Note that the xmlns attribute is required.
<span class="icon-home decorative-large-icon"><span class="visually-hidden">Home</span></span>
Using:
.icon-home::before {
display: inline-block;
width: 1em;
height: 1em;
vertical-align: bottom;
content: "";
background-color: currentcolor;
background-size: contain;
mask-image: escape-svg(url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M22.2 12.4a1 1 0 0 1-.6.4h-3v7c0 1.4-1.1 2.5-2.5 2.5h-8c-1.3 0-2.4-1.1-2.4-2.5v-7h-3a.6.6 0 0 1-.5-1.1l9.5-9.5a1 1 0 0 1 .9 0l2.3 2.4a.6.6 0 0 1-.8.9l-2-2-8 8h2.2q.6 0 .6.6v7.7Q7 21 8.1 21h8q1.1 0 1.2-1.2v-7.7q0-.5.6-.6h2.2l-3.8-4a.6.6 0 1 1 1-.9l4.8 5a1 1 0 0 1 .1.8M14.6 18h-3a1 1 0 0 1-1-1v-2.9a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1v3a1 1 0 0 1-1 .9m-.4-3.6h-2.4v2.3h2.4z'/></svg>"));
}
Inline SVG
This technique should only be used if you have few icons to render, and if they are used only once in your website.
You can embed your icons directly within the HTML of your page (as opposed to an external image file). This way to use SVGs can benefit of the power of currentColor for easy coloring and theming.
<svg fill="currentColor" viewBox="0 0 24 24" class="decorative-large-icon" aria-hidden="true">
<path fill-rule="evenodd" d="M13.48 13.88c.39 0 .7.32.7.7v3.52a.7.7 0 0 1-.7.7H9.96a.7.7 0 0 1-.7-.7v-3.52c0-.38.31-.7.7-.7zm-2.81 3.51h2.1v-2.1h-2.1zm5.92 6.11H6.88A2.9 2.9 0 0 1 4 20.63v-3.47a.7.7 0 0 1 1.4 0v3.47c0 .8.67 1.46 1.48 1.46h9.71a1.47 1.47 0 0 0 1.47-1.46v-8.45a1.36 1.36 0 0 0-1.36-1.36H6.77a1.36 1.36 0 0 0-1.36 1.36v1.47a.7.7 0 0 1-1.41 0v-1.47a2.77 2.77 0 0 1 2.74-2.76V5.98A5 5 0 0 1 11.72 1a5 5 0 0 1 4.98 4.98v3.44a2.77 2.77 0 0 1 2.77 2.76v8.45a2.9 2.9 0 0 1-2.88 2.87M15.3 5.98a3.6 3.6 0 0 0-3.57-3.57 3.6 3.6 0 0 0-3.57 3.57V9.4h7.14z" clip-rule="evenodd"/>
</svg>
External SVG
You can use SVG through an <img /> tag when:
- you only have few icons to render
- you don’t need to change the icons colors. For that reason, we do not recommend to use that technique, so it won’t be documented here.
Accessibility
Decorative icons
Purely decorative icons (like repeating information of an adjacent text) must be hidden to assistive technologies:
- for
<svg>or<span>tags, use the attributearia-hidden="true" - for
<img />, use an emptyaltattribute - CSS background images are intended to be decorative
You should set decorative icon sizes in px so they do not scale with text zoom, leaving room for surrounding meaningful content.
Informative icons
If the icon is meaningful with no visible adjacent text, e.g. indication in a table or only content of a button, you have to provide an appropriate alternative text with the description of the icon or the description of the action triggered.
The best way to do this is to keep the icon hidden to assistive technologies (see above) and add a visually hidden label which will be perceived by assistive technologies, by using the .visually-hidden class. You can also use an aria-label on the containing interactive element to provide an accessible name. For external images within the <img /> tag, you can also fill the alt attribute directly.
Remember that you cannot use external images inside interactive elements because the color won’t change with the element’s status (hover, active, focus...), see External SVG image.
You should set informative icon sizes in rem so they scale with text zoom.
<button type="button" class="btn btn-icon btn-default">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#trash" />
</svg>
<span class="visually-hidden">Delete</span>
</button>
<button type="button" class="btn btn-icon btn-default" aria-label="Delete">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#trash" />
</svg>
</button>
<button type="button" class="btn btn-icon btn-default">
<span class="icon si si-settings" aria-hidden="true"></span>
<span class="visually-hidden">Open settings</span>
</button>
<button type="button" class="btn btn-icon btn-default" aria-label="Open settings">
<span class="icon si si-settings" aria-hidden="true"></span>
</button>
<div class="d-inline-block bg-always-white">
<img src="/sosh/docs/1.6/assets/img/heart-empty.svg" alt="Favorite" class="bl-large-icon" />
</div>
Colors
To color icons, you can:
- use color utilities classes like
.text-brand-primary,.text-disabledor.text-status-positivethat change current color value. - specify a color using CSS variables like
--bs-color-content-brand-primary,--bs-color-content-disabledor--bs-color-content-status-positive.
For SVGs (SVG sprites, inline SVGs or CSS mask image SVGs), the fill="currentColor" attribute is required on the <svg> or <symbol> tag, if you want to change the icons color on the fly (for example on hover): it will make the icon inherit color from itself or its parent containers. For CSS mask image SVGs, the background-color: currentcolor CSS property should be set.
Status colors
Here are some examples of status color utilities and CSS variables designed to provide feedback or information to the user. The colors info, positive, warning, and negative are intended for use only with functional icons. The accent color is intended to highlight something and can be used with any icon. Note that, to ensure accessibility, the warning icon uses two different colors for its inner and outer shapes, so you cannot directly use the color utility or CSS variable; see the section on the accessible warning icon for more details.
See below some information about the normal contexts of use of these status colors.
| Color utility | Color CSS variable | Context of use |
|---|---|---|
.text-status-info | --bs-color-content-status-info | Use to communicate a feedback. It’s more important than a neutral color. |
.text-status-positive | --bs-color-content-status-positive | Use to communicate a positive action, a confirmation or a positive feedback. |
| NA | --bs-icon-color-content-status-warning-external-shape and --bs-icon-color-content-status-warning-internal-shape | Use to display an information that requires more attention, or an action from the user. |
.text-status-negative | --bs-color-content-status-negative | Use to communicate something negative. It can be a destructive action, an error state, or a negative feedback. |
.text-status-accent | --bs-color-content-status-accent | Used to highlight or draw attention to a specific element. |
Info Success Warning Important Accent
Info Success Warning Important Accent
<p class="p-small bg-primary d-inline-flex align-items-center gap-xsmall" data-bs-theme="light">
<svg class="text-status-info decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-info" />
</svg> Info
<svg class="text-status-positive decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-positive" />
</svg> Success
<svg class="decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-warning" />
</svg> Warning
<svg class="text-status-negative decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-negative" />
</svg> Important
<svg class="text-status-accent decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg> Accent
</p>
<p class="p-small bg-always-black d-inline-flex align-items-center gap-xsmall" data-bs-theme="dark">
<svg class="text-status-info decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-info" />
</svg> Info
<svg class="text-status-positive decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-positive" />
</svg> Success
<svg class="decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-warning" />
</svg> Warning
<svg class="text-status-negative decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-negative" />
</svg> Important
<svg class="text-status-accent decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg> Accent
</p>
Accessible warning icon
To ensure accessibility through sufficient contrast, OUDS provides a dedicated warning icon with two distinct colors for its external and internal shapes. This design choice enhances visibility and clarity, making it easier for users to recognize and understand warning messages.
Here is a SVG symbol to insert into your SVG sprite. It uses the CSS variables --bs-icon-color-content-status-warning-external-shape and --bs-icon-color-content-status-warning-internal-shape to color the external and internal shapes of the icon respectively, changing according to color mode. See below to know more about SVG sprites.
<symbol viewBox="0 0 24 24" id="functional-status-warning">
<path fill="var(--bs-icon-color-content-status-warning-external-shape)" d="M12 3.36c.786 0 1.473.43 1.843 1.072l7.467 12.96c.184.32.29.692.29 1.088 0 1.193-.955 2.16-2.133 2.16H4.533c-1.178 0-2.132-.967-2.133-2.16 0-.396.106-.769.29-1.088l.018-.03.001-.003 7.448-12.927A2.127 2.127 0 0 1 12 3.36Zm0 12.72c-.334 0-.618.12-.85.36-.233.24-.35.52-.35.84 0 .33.117.612.35.847.218.23.528.357.85.353.335 0 .618-.118.85-.353.234-.235.35-.517.35-.847 0-.32-.116-.6-.35-.84a1.142 1.142 0 0 0-.85-.36Zm.001-9.6c-.643 0-1.171.455-1.201 1.025l.24 7.135h1.92l.24-7.135c-.03-.57-.556-1.025-1.199-1.025Z"/>
<path fill="var(--bs-icon-color-content-status-warning-internal-shape)" d="M10.8 7.505c.03-.57.558-1.025 1.2-1.025.643 0 1.17.455 1.2 1.025l-.24 7.135h-1.92l-.24-7.135Zm2.05 10.622a1.15 1.15 0 0 1-.85.353 1.15 1.15 0 0 1-.85-.353 1.16 1.16 0 0 1-.35-.847c0-.32.116-.6.35-.84.232-.24.516-.36.85-.36.334 0 .618.12.85.36.234.24.35.52.35.84 0 .33-.116.613-.35.847Z"/>
</symbol>
Then, you can use it like this:
<svg class="decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#functional-status-warning" />
</svg>
Please note that this icon cannot be rendered by a Web font, due to its two colors.
Other colors
Here are some examples of other color utilities and CSS variables used with icons.
<p class="p-small bg-primary d-inline-flex align-items-center gap-xsmall" data-bs-theme="light">
<svg class="decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
<svg class="decorative-small-icon text-primary" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#download" />
</svg>
<svg class="decorative-small-icon text-disabled" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#trash" />
</svg>
<span class="icon si si-settings text-muted decorative-small-icon" aria-hidden="true"></span>
</p>
<p class="p-small bg-always-black d-inline-flex align-items-center gap-xsmall" data-bs-theme="dark">
<svg class="decorative-small-icon" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
<svg class="decorative-small-icon" style="color: var(--bs-color-content-brand-primary)" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#download" />
</svg>
<svg class="decorative-small-icon" style="color: var(--bs-color-content-disabled)" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#trash" />
</svg>
<span class="icon si si-settings decorative-small-icon" style="color: var(--bs-color-content-muted)" aria-hidden="true"></span>
</p>
Sizing
Note that you can use the utility classes provided in the icons sizing utilities documentation to adjust the size of your icons.
Layout
Sometimes you need a different structure to handle larger titles, or paragraphs that wrap over several lines. Here are some examples to handle these use cases. We’ve set arbitrary spacings, but align them with your design.
Centered on text block
This is the default behavior of our DOM.
H1 with large icon and a very long title to see how it behaves while being wrapped
<div class="d-flex align-items-center">
<svg class="hxl-large-icon me-scaled-small text-status-info" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#internet" />
</svg>
<h1 class="mb-none">H1 with large icon and a very long title to see how it behaves while being wrapped</h1>
</div>
Default long paragraph with large icon. It stands here in order for you to see how the icon should behave when it’s placed next to a long paragraph. Whenever the paragraph stands on multiple lines please prefer using a block element and not an inline element so there will no strange behaviors.
<div class="d-flex align-items-center">
<svg class="bm-large-icon me-scaled-small text-status-info" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#internet" />
</svg>
<p class="mb-none">
Default long paragraph with large icon. It stands here in order for you to see how the icon should behave when it’s placed next to a long paragraph. Whenever the paragraph stands on multiple lines please prefer using a block element and not an inline element so there will no strange behaviors.
</p>
</div>
Above text block
You can also have the icon above the text block.
H1 with large icon and a very long title to see how it behaves while being wrapped
<div>
<svg class="hxl-large-icon mb-scaled-xsmall text-status-info" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#internet" />
</svg>
<h1 class="mb-none">H1 with large icon and a very long title to see how it behaves while being wrapped</h1>
</div>
Default long paragraph with large icon. It stands here in order for you to see how the icon should behave when it’s placed next to a long paragraph. Whenever the paragraph stands on multiple lines please prefer using a block element and not an inline element so there will no strange behaviors.
<div>
<svg class="bm-large-icon mb-scaled-2xsmall text-status-info" aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#internet" />
</svg>
<p class="mb-none">
Default long paragraph with large icon. It stands here in order for you to see how the icon should behave when it’s placed next to a long paragraph. Whenever the paragraph stands on multiple lines please prefer using a block element and not an inline element so there will no strange behaviors.
</p>
</div>