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	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, no se compila.
`class`	Opcional	Variable para el nombre de la clase si no quieres que sea la misma que la propiedad. En caso de que no proporciones la clave `class` y la clave `property` sea un array de strings, el nombre de la clase será el primer elemento del array `property`.
`state`	Opcional	Lista de variantes de pseudoclases como `:hover` o `:focus` a generar para la utilidad. Sin valor predeterminado.
`responsive`	Opcional	Booleano que indica si se necesitan generar clases responsivas. `false` por defecto.
`rfs`	Opcional	Booleano para habilitar el reescalado fluido. Echa un vistazo a la página de RFS para descubrir cómo funciona. `false` por defecto.
`print`	Opcional	Booleano que indica si se necesitan generar clases de impresión. `false` por defecto.
`rtl`	Opcional	Booleano que indica si la utilidad debe mantenerse en RTL. `true` por defecto.

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

Prefijo de clase personalizado

Usa la opción class para cambiar el prefijo de clase usado en el CSS compilado:

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

Salida:

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

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

Utilidades responsivas

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

Cambiando 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,
  ),
);

Utilidades de 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).

Usando 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.

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/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

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/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

Habilitar responsivas

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/utilities";

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

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/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

Eliminar utilidades

Elimina cualquiera de las utilidades predeterminadas estableciendo la clave del grupo en null. Por ejemplo, para eliminar todas nuestras utilidades de width, crea un $utilities map-merge y añade "width": null dentro.

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

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

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.