Utility API

La utility API es una herramienta basada en Sass para generar clases utilitarias.

On this page

Las utilidades de Bootstrap se generan con nuestra utility API y se pueden usar para modificar o ampliar nuestro conjunto predeterminado de clases utilitarias mediante Sass. Nuestra utility API se basa en una serie de mapas y funciones de Sass para generar familias de clases con varias opciones. Si no estás familiarizado con los mapas de Sass, lee la documentación oficial de Sass para empezar.

El mapa $utilities contiene todas nuestras utilidades y luego se combina con tu mapa personalizado de $utilities, si existe. El mapa de utilidades contiene una lista de grupos de utilidades con claves que aceptan las siguientes opciones:

Opción	Tipo	Valor predeterminado	Descripción
`property`	Required	–	Nombre de la propiedad, puede ser un string o un array de strings (p. ej., paddings o márgenes horizontales).
`values`	Required	–	Lista de valores, o un mapa si no quieres que el nombre de la clase sea el mismo que el valor. Si se usa `null` como clave del mapa, `class` no se antepone al nombre de la clase.
`class`	Opcional	null	Nombre de la clase generada. Si no se proporciona y `property` es un array de strings, `class` será por defecto el primer elemento del array `property`. Si no se proporciona y `property` es un string, las claves de `values` se usan para los nombres de `class`.
`css-var`	Opcional	`false`	Booleano para generar variables CSS en lugar de reglas CSS.
`css-variable-name`	Opcional	null	Nombre personalizado sin prefijo para la variable CSS dentro del conjunto de reglas.
`local-vars`	Opcional	null	Mapa de variables CSS locales a generar además de las reglas CSS.
`state`	Opcional	null	Lista de variantes de pseudo-clases (p. ej., `:hover` o `:focus`) a generar.
`responsive`	Opcional	`false`	Booleano que indica si se deben generar clases responsive.
`rfs`	Opcional	`false`	Booleano para habilitar el redimensionado fluido con RFS.
`print`	Opcional	`false`	Booleano que indica si se necesitan generar clases de impresión.
`rtl`	Opcional	`true`	Booleano que indica si la utilidad debe mantenerse en RTL.

API explicada

Todas las variables de utilidades se añaden a la variable $utilities dentro de nuestra hoja de estilos _utilities.scss. Cada grupo de utilidades se ve más o menos así:

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

Lo cual produce lo siguiente:

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

Propiedad

La clave property es obligatoria para cualquier utilidad y debe contener una propiedad CSS válida. Esta propiedad se usa en el conjunto de reglas de la utilidad generada. Cuando se omite la clave class, también sirve como nombre de clase por defecto. Considera la utilidad text-decoration:

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

Salida:

.text-decoration-none { text-decoration: none !important; }
.text-decoration-underline { text-decoration: underline !important; }
.text-decoration-line-through { text-decoration: line-through !important; }

Valores

Usa la clave values para especificar qué valores de la property especificada deben usarse en los nombres de clase y reglas generadas. Puede ser una lista o un mapa (establecido en las utilidades o en una variable Sass).

Como una lista, como en las utilidades de text-decoration:

values: none underline line-through

Como un mapa, como en las utilidades de opacity:

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

Como una variable Sass que establece la lista o el mapa, como en nuestras utilidades de position:

values: $position-values

Clase

Usa la opción class para cambiar el prefijo de clase usado en el CSS compilado. Por ejemplo, para cambiar de .opacity-* a .o-*:

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

Salida:

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

Si class: null, genera clases para cada una de las claves de values:

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

Salida:

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

Utilidades de variables CSS

Establece la opción booleana css-var en true y la API generará variables CSS locales para el selector dado en lugar de las reglas habituales property: value. Añade un css-variable-name opcional para establecer un nombre de variable CSS diferente al nombre de la clase.

Considera nuestras utilidades .text-opacity-*. Si añadimos la opción css-variable-name, obtendremos una salida personalizada.

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

Salida:

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

Variables CSS locales

Usa la opción local-vars para especificar un mapa Sass que generará variables CSS locales dentro del conjunto de reglas de la clase de utilidad. Ten en cuenta que puede requerir trabajo adicional consumir esas variables CSS locales en las reglas CSS generadas. Por ejemplo, considera nuestras utilidades .bg-*:

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

Salida:

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

Estados

Usa la opción state para generar variaciones de pseudoclases. Ejemplos de pseudoclases son :hover y :focus. Cuando se proporciona una lista de estados, se crean nombres de clase para esa pseudoclase. Por ejemplo, para cambiar la opacidad al pasar el cursor, añade state: hover y obtendrás .opacity-hover:hover en tu CSS compilado.

¿Necesitas múltiples pseudoclases? Usa una lista de estados separada por espacios: state: hover focus.

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

Salida:

.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

Añade el booleano responsive para generar utilidades responsivas (p. ej., .opacity-md-25) en todos los breakpoints.

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

Salida:

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

Impresión

Habilitar la opción print también generará clases utilitarias para impresión, que solo se aplican dentro de la media query @media print { ... }.

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

Salida:

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

Importancia

Todas las utilidades generadas por la API incluyen !important para asegurar que anulen los componentes y las clases modificadoras según lo previsto. Puedes activar o desactivar este ajuste globalmente con la variable $enable-important-utilities (por defecto es true).

Uso de la API

Ahora que estás familiarizado con cómo funciona la utilities API, aprende a añadir tus propias clases personalizadas y a modificar nuestras utilidades predeterminadas.

Sobrescribir utilidades

Sobrescribe las utilidades existentes usando la misma clave. Por ejemplo, si quieres clases utilitarias de overflow responsivas adicionales, puedes hacer esto:

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

Añadir utilidades

Se pueden añadir nuevas utilidades al mapa predeterminado de $utilities con un map-merge. Asegúrate de que nuestros archivos Sass requeridos y _utilities.scss se importan primero, luego usa map-merge para añadir tus utilidades adicionales. Por ejemplo, así es como se añade una utilidad responsiva de cursor con tres valores.

@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";

Modificar utilidades

Modifica las utilidades existentes en el mapa predeterminado de $utilities con las funciones map-get y map-merge. En el ejemplo de abajo, estamos añadiendo un valor adicional a las utilidades de width. Comienza con un map-merge inicial y luego especifica qué utilidad quieres modificar. A partir de ahí, obtén el mapa anidado "width" con map-get para acceder y modificar las opciones y valores de la utilidad.

@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";

Habilitar responsive

Puedes habilitar clases responsivas para un conjunto existente de utilidades que actualmente no son responsivas por defecto. Por ejemplo, para hacer que las clases de border sean responsivas:

@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";

Esto ahora generará variaciones responsivas de .border y .border-0 para cada breakpoint. Tu CSS generado se verá así:

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

Renombrar utilidades

¿Te faltan utilidades de v4, o estás acostumbrado a otra convención de nombres? La utilities API se puede usar para sobrescribir la class resultante de una utilidad dada—por ejemplo, para renombrar las utilidades .ms-* a las antiguas .ml-*:

@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";

Eliminar utilidades

Elimina cualquiera de las utilidades por defecto con la función Sass map-remove().

@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";

También puedes usar la función Sass map-merge() y establecer la clave del grupo en null para eliminar la utilidad.

@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";

Añadir, eliminar, modificar

Puedes añadir, eliminar y modificar muchas utilidades a la vez con la función Sass map-merge(). Así es como puedes combinar los ejemplos anteriores en un mapa más grande.

@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";

Eliminar utilidad en RTL

Algunos casos extremos hacen que el estilo RTL sea difícil, como los saltos de línea en árabe. Por lo tanto, las utilidades se pueden eliminar de la salida RTL estableciendo la opción rtl en false:

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

Salida:

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

Esto no produce nada en RTL, gracias a la directiva de control remove de RTLCSS.