API de utilidades (Utility API)

La API de utilidades es una herramienta basada en Sass para generar clases de utilidad.

En esta página

Las utilidades de Bootstrap se generan con nuestra API de utilidades y se pueden usar para modificar o extender nuestro conjunto predeterminado de clases de utilidad a través de Sass. Nuestra API de utilidades 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 comenzar.

El mapa $utilities contiene todas nuestras utilidades y luego se fusiona con tu mapa $utilities personalizado, si está presente. El mapa de utilidades contiene una lista con clave de grupos de utilidades que aceptan las siguientes opciones:

Opción	Tipo	Valor predeterminado	Descripción
`property`	Requerido	–	Nombre de la propiedad, puede ser una cadena o un array de cadenas (por ejemplo, rellenos o márgenes horizontales).
`values`	Requerido	–	Lista de valores, o un mapa si no deseas que el nombre de la clase sea el mismo que el valor. Si se utiliza `null` como clave del mapa, no se antepone `class` al nombre de la clase.
`class`	Opcional	null	Nombre de la clase generada. Si no se proporciona y `property` es un array de cadenas, `class` tendrá como valor predeterminado el primer elemento del array `property`. Si no se proporciona y `property` es una cadena, las claves de `values` se utilizan 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 para generar además de las reglas CSS.
`state`	Opcional	null	Lista de variantes de pseudoclases (por ejemplo, `:hover` o `:focus`) a generar.
`responsive`	Opcional	`false`	Booleano que indica si se deben generar clases responsivas.
`rfs`	Opcional	`false`	Booleano para habilitar el reescalado fluido con RFS.
`print`	Opcional	`false`	Booleano que indica si se deben generar clases de impresión.
`rtl`	Opcional	`true`	Booleano que indica si la utilidad debe mantenerse en RTL.

Explicación de la API

Todas las variables de utilidad se agregan a la variable $utilities dentro de nuestra hoja de estilo _utilities.scss. Cada grupo de utilidades se ve 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; }

Property (Propiedad)

La clave property requerida debe establecerse para cualquier utilidad y debe contener una propiedad CSS válida. Esta propiedad se utiliza en el conjunto de reglas de la utilidad generada. Cuando se omite la clave class, también sirve como nombre de clase predeterminado. 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; }

Values (Valores)

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

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

values: none underline line-through

Como un mapa, como con 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

Class (Clase)

Usa la opción class para cambiar el prefijo de clase utilizado 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. Agrega un css-variable-name opcional para establecer un nombre de variable CSS diferente al nombre de la clase.

Considera nuestras utilidades .text-opacity-*. Si agregamos 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

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

States (Estados)

Utiliza 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, agrega state: hover y obtendrás .opacity-hover:hover en tu CSS compilado.

¿Necesitas varias pseudoclases? Usa una lista de estados separados 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; }

Responsivo

Agrega el booleano responsive para generar utilidades responsivas (por ejemplo, .opacity-md-25) en todos los puntos de interrupción.

$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 (Print)

Habilitar la opción print también generará clases de utilidad para la 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 garantizar que anulen los componentes y las clases modificadoras según lo previsto. Puedes alternar esta configuración 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 API de utilidades, aprende cómo agregar tus propias clases personalizadas y modificar nuestras utilidades predeterminadas.

Anular utilidades

Anula las utilidades existentes utilizando la misma clave. Por ejemplo, si deseas clases de utilidad de desbordamiento responsivo adicionales, puedes hacer esto:

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

Añadir utilidades

Se pueden agregar nuevas utilidades al mapa $utilities predeterminado con un map-merge. Asegúrate de importar primero nuestros archivos Sass requeridos y _utilities.scss, luego usa el map-merge para agregar tus utilidades adicionales. Por ejemplo, aquí se explica cómo agregar una utilidad de cursor responsiva 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 $utilities predeterminado con las funciones map-get y map-merge. En el siguiente ejemplo, agregamos un valor adicional a las utilidades de ancho (width). Comienza con un map-merge inicial y luego especifica qué utilidad deseas modificar. Desde allí, obtén el mapa "width" anidado 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 responsivo

Puedes habilitar clases responsivas para un conjunto existente de utilidades que actualmente no son responsivas por defecto. Por ejemplo, para hacer que las clases 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 punto de interrupción. 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 { ... }
}

Cambiar el nombre de las utilidades

¿Faltan utilidades de la versión 4 o estás acostumbrado a otra convención de nomenclatura? La API de utilidades se puede usar para anular la class resultante de una utilidad determinada; por ejemplo, para cambiar el nombre de 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 predeterminadas 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";

// Eliminar múltiples utilidades con una lista separada por comas
$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 agregar, eliminar y modificar muchas utilidades a la vez con la función Sass map-merge(). Aquí se explica cómo 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,
  (
    // Eliminar la utilidad `width`
    "width": null,
    // Hacer que una utilidad existente sea responsiva
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
    // Añadir nuevas utilidades
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

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

Eliminar utilidad en RTL

Algunos casos excepcionales dificultan el diseño RTL, como los saltos de línea en árabe. Por lo tanto, las utilidades se pueden excluir 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 genera nada en RTL, gracias a la directiva de control remove de RTLCSS.