Bootstrap 5.2 / Utilities

Utility-API

De utility-API is een op Sass gebaseerd hulpmiddel om utility-klassen te genereren.

De utilities van Bootstrap worden gegenereerd met onze utility-API en kunnen worden gebruikt om onze standaardset utility-klassen via Sass aan te passen of uit te breiden. Onze utility-API is gebaseerd op een reeks Sass-maps en -functies om families van klassen met uiteenlopende opties te genereren. Ben je niet bekend met Sass-maps, lees dan eerst de officiële Sass-documentatie om op weg te komen.

De $utilities-map bevat al onze utilities en wordt later samengevoegd met je eigen $utilities-map, als die er is. De utility-map bevat een lijst met utility-groepen op sleutel, die de volgende opties accepteren:

Optie	Type	Standaard waarde	Omschrijving
`property`	Verplicht	–	Naam van de eigenschap; dit kan een string of een array van strings zijn (bijv. horizontale paddings of marges).
`values`	Verplicht	–	Lijst met waarden, of een map als je niet wilt dat de klassenaam gelijk is aan de waarde. Als `null` als mapsleutel wordt gebruikt, wordt `class` niet vóór de klassenaam geplaatst.
`class`	Optioneel	null	Naam van de gegenereerde klasse. Wordt die niet opgegeven en is `property` een array van strings, dan is `class` standaard het eerste element van de `property`-array. Wordt die niet opgegeven en is `property` een string, dan worden de sleutels van `values` als `class`-namen gebruikt.
`css-var`	Optioneel	`false`	Boolean om CSS-variabelen te genereren in plaats van CSS-regels.
`css-variable-name`	Optioneel	null	Eigen naam zonder prefix voor de CSS-variabele binnen de ruleset.
`local-vars`	Optioneel	null	Map met lokale CSS-variabelen die naast de CSS-regels worden gegenereerd.
`state`	Optioneel	null	Lijst met pseudo-klasse-varianten (bijv. `:hover` of `:focus`) die gegenereerd moeten worden.
`responsive`	Optioneel	`false`	Boolean die aangeeft of er responsieve klassen gegenereerd moeten worden.
`rfs`	Optioneel	`false`	Boolean om vloeiend herschalen met RFS in te schakelen.
`print`	Optioneel	`false`	Boolean die aangeeft of er printklassen gegenereerd moeten worden.
`rtl`	Optioneel	`true`	Boolean die aangeeft of de utility in RTL behouden moet blijven.

De API uitgelegd

Alle utility-variabelen worden aan de variabele $utilities in onze stylesheet _utilities.scss toegevoegd. Elke groep utilities ziet er ongeveer zo uit:

SCSS

$utilities: (
  "opacity": (
    property: opacity,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Wat het volgende oplevert:

CSS

.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

Property

De verplichte sleutel property moet voor elke utility worden ingesteld en moet een geldige CSS-eigenschap bevatten. Deze eigenschap wordt gebruikt in de ruleset van de gegenereerde utility. Wanneer de sleutel class wordt weggelaten, dient hij ook als standaardklassenaam. Neem de text-decoration-utility:

SCSS

$utilities: (
  "text-decoration": (
    property: text-decoration,
    values: none underline line-through
  )
);

Uitvoer:

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

Gebruik de sleutel values om aan te geven welke waarden voor de opgegeven property in de gegenereerde klassenamen en regels gebruikt moeten worden. Dit kan een lijst of een map zijn (ingesteld in de utilities of in een Sass-variabele).

Als lijst, zoals bij de text-decoration-utilities:

SCSS

values: none underline line-through

Als map, zoals bij de opacity-utilities:

SCSS

values: (
  0: 0,
  25: .25,
  50: .5,
  75: .75,
  100: 1,
)

Als Sass-variabele die de lijst of map instelt, zoals in onze position-utilities:

SCSS

values: $position-values

Class

Gebruik de optie class om de klasseprefix in de gecompileerde CSS te wijzigen. Bijvoorbeeld om van .opacity-* naar .o-* te gaan:

SCSS

$utilities: (
  "opacity": (
    property: opacity,
    class: o,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Uitvoer:

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; }

Bij class: null worden klassen gegenereerd voor elk van de sleutels in values:

SCSS

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

Uitvoer:

CSS

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

CSS-variabele-utilities

Zet de booleaanse optie css-var op true en de API genereert lokale CSS-variabelen voor de gegeven selector in plaats van de gebruikelijke property: value-regels. Voeg optioneel css-variable-name toe om een andere naam voor de CSS-variabele dan de klassenaam in te stellen.

Neem onze .text-opacity-*-utilities. Als we de optie css-variable-name toevoegen, krijgen we een aangepaste uitvoer.

SCSS

$utilities: (
  "text-opacity": (
    css-var: true,
    css-variable-name: text-alpha,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

Uitvoer:

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; }

Lokale CSS-variabelen

Gebruik de optie local-vars om een Sass-map op te geven die lokale CSS-variabelen binnen de ruleset van de utility-klasse genereert. Houd er rekening mee dat het extra werk kan kosten om die lokale CSS-variabelen in de gegenereerde CSS-regels te gebruiken. Neem bijvoorbeeld onze .bg-*-utilities:

SCSS

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

Uitvoer:

CSS

.bg-primary {
  --bs-bg-opacity: 1;
  background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}

States

Gebruik de optie state om pseudo-klasse-varianten te genereren. Voorbeelden van pseudo-klassen zijn :hover en :focus. Wanneer je een lijst met states opgeeft, worden er klassenamen voor die pseudo-klasse aangemaakt. Wil je bijvoorbeeld de dekking bij hover wijzigen, voeg dan state: hover toe en krijg je .opacity-hover:hover in je gecompileerde CSS.

Meerdere pseudo-klassen nodig? Gebruik een door spaties gescheiden lijst met states: state: hover focus.

SCSS

$utilities: (
  "opacity": (
    property: opacity,
    class: opacity,
    state: hover,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Uitvoer:

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; }

Responsief

Voeg de boolean responsive toe om responsieve utilities (bijv. .opacity-md-25) op alle breakpoints te genereren.

SCSS

$utilities: (
  "opacity": (
    property: opacity,
    responsive: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Uitvoer:

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

Wanneer je de optie print inschakelt, worden er daarnaast utility-klassen voor afdrukken gegenereerd, die alleen binnen de media query @media print { ... } worden toegepast.

SCSS

$utilities: (
  "opacity": (
    property: opacity,
    print: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Uitvoer:

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; }
}

Belangrijkheid

Alle utilities die door de API worden gegenereerd bevatten !important, zodat ze componenten en modifier-klassen overschrijven zoals bedoeld. Je kunt deze instelling globaal schakelen met de variabele $enable-important-utilities (standaard true).

De API gebruiken

Nu je weet hoe de utilities-API werkt, leer je hier hoe je je eigen klassen toevoegt en onze standaard-utilities aanpast.

Utilities overschrijven

Overschrijf bestaande utilities door dezelfde sleutel te gebruiken. Wil je bijvoorbeeld extra responsieve overflow-utility-klassen, dan doe je dit:

SCSS

$utilities: (
  "overflow": (
    responsive: true,
    property: overflow,
    values: visible hidden scroll auto,
  ),
);

Utilities toevoegen

Nieuwe utilities kunnen met een map-merge aan de standaard $utilities-map worden toegevoegd. Zorg dat onze verplichte Sass-bestanden en _utilities.scss eerst geïmporteerd worden en gebruik daarna map-merge om je extra utilities toe te voegen. Zo voeg je bijvoorbeeld een responsieve cursor-utility met drie waarden toe.

SCSS

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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";

Utilities aanpassen

Pas bestaande utilities in de standaard $utilities-map aan met de functies map-get en map-merge. In het onderstaande voorbeeld voegen we een extra waarde aan de width-utilities toe. Begin met een eerste map-merge en geef daarna aan welke utility je wilt aanpassen. Haal vervolgens de geneste "width"-map met map-get op om de opties en waarden van de utility te benaderen en aan te passen.

SCSS

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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";

Responsief inschakelen

Je kunt responsieve klassen inschakelen voor een bestaande set utilities die standaard niet responsief is. Bijvoorbeeld om de border-klassen responsief te maken:

SCSS

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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";

Dit genereert nu responsieve varianten van .border en .border-0 voor elk breakpoint. Je gegenereerde CSS ziet er dan zo uit:

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 { ... }
}

Utilities hernoemen

Mis je utilities uit v4, of ben je een andere naamgevingsconventie gewend? De utilities-API kan worden gebruikt om de resulterende class van een bepaalde utility te overschrijven — bijvoorbeeld om .ms-*-utilities te hernoemen naar het oude .ml-*:

SCSS

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@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";

Utilities verwijderen

Verwijder standaard-utilities met de Sass-functie map-remove().

SCSS

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

// Verwijder meerdere utilities met een door komma's gescheiden lijst
$utilities: map-remove($utilities, "width", "float");

@import "bootstrap/scss/utilities/api";

Je kunt ook de Sass-functie map-merge() gebruiken en de groepssleutel op null zetten om de utility te verwijderen.

SCSS

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

@import "bootstrap/scss/utilities/api";

Toevoegen, verwijderen, aanpassen

Je kunt veel utilities in één keer toevoegen, verwijderen en aanpassen met de Sass-functie map-merge(). Zo combineer je de vorige voorbeelden tot één grotere map.

SCSS

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    // Verwijder de `width`-utility
    "width": null,

    // Maak een bestaande utility responsief
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),

    // Voeg nieuwe utilities toe
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Een utility in RTL verwijderen

Bepaalde randgevallen maken RTL-styling lastig, zoals regelafbrekingen in het Arabisch. Utilities kunnen daarom uit de RTL-uitvoer worden weggelaten door de optie rtl op false te zetten:

SCSS

$utilities: (
  "word-wrap": (
    property: word-wrap word-break,
    class: text,
    values: (break: break-word),
    rtl: false
  ),
);

Uitvoer:

CSS

/* rtl:begin:remove */
.text-break {
  word-wrap: break-word !important;
  word-break: break-word !important;
}
/* rtl:end:remove */

Dit levert in RTL niets op, dankzij de RTLCSS-control-directive remove.