Background

The auro-background element is an easy-to-use mobile-first alternative to writing custom CSS for background colors or images with automatically scoped media queries. Use independently or in the slot of another custom element such as auro-banner.

The auro-background component accepts 4 properties - bg, height, width, and inset that serve as the default at all breakpoints. height, width, and inset are not required and sizing will scale to the content when omitted. Additionally, there is a separate property for each supported breakpoint (bgSm, bgMd, bgLg, heightSm, heightMd, heightLg, widthSm, widthMd, widthLg). If you don't set a specific size property, the smaller property will be used.

These properties map to the compound CSS background property and CSS properties of height, width, and padding. Anything you can do within the scope of those CSS rules you can do here.

See CSS Background Image Generator for a helpful code generation tool.

Use Cases

The <auro-background> element should be used in situations where users may:

• Need to apply a background image or color to a specific section of content
• Require responsive background images that change at different breakpoints

Install

$ npm i @aurodesignsystem/auro-background

Define Dependency in Project

Defining the dependency within each project that is using the <auro-background> component.

import "@aurodesignsystem/auro-background";

Use CDN

In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.

<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-background@latest/+esm"></script>

Basic Example

<auro-background bg="url(https://images.contentstack.io/v3/assets/blt2cefe12c88e9dd91/blt4dde4105498391f8/6633c2581dbb0973c00b8783/ad2.png) center center/cover no-repeat">
  <div style="color: var(--ds-color-text-primary-inverse); display: flex; flex-direction: column; align-items: center; justify-content: center;">
    <auro-header level="2" visualLevel="3">View all destinations</auro-header>
    <auro-hyperlink type="cta" variant="secondary" href="#" size="xs" style="padding-bottom: 4px;">See where we fly</auro-hyperlink>
  </div>
</auro-background>

Custom Component Registration for Version Management

There are two key parts to every Auro component: the class and the custom element definition. The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML.

When you install the component as described on the Install page, the class is imported automatically, and the component is registered globally for you.

However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.

You can do this by importing only the component class and using the register(name) method with a unique name:

// Import the class only
import { AuroBackground } from '@aurodesignsystem/auro-background/class';

// Register with a custom name if desired
AuroBackground.register('custom-background');

This will create a new custom element <custom-background> that behaves exactly like <auro-background>, allowing both to coexist on the same page without interfering with each other.

<custom-background bg="url(https://images.contentstack.io/v3/assets/blt2cefe12c88e9dd91/blt4dde4105498391f8/6633c2581dbb0973c00b8783/ad2.png) center center/cover no-repeat">
  <div style="color: var(--ds-color-text-primary-inverse); display: flex; flex-direction: column; align-items: center; justify-content: center;">
    <auro-header level="2" visualLevel="3">View all destinations</auro-header>
    <auro-hyperlink type="cta" variant="secondary" href="#" size="xs">See where we fly</auro-hyperlink>
  </div>
</custom-background>