Skip to main content Home About the Design SystemRoadmap OverviewDesignersDevelopers OverviewColorGridIconographyInteractionsSpacingTypography Overview Global colorBox shadowTypographyBorderOpacitySpaceLengthIconBreakpointsMedia queries All elements Accordion Alert Announcement Audio player Avatar Back to top Badge Blockquote Breadcrumb Button Card Chip Code block Call to action Dialog Disclosure Footer Health index Icon Jump links Menu dropdown Navigation link Navigation (primary) Navigation (secondary) Navigation (vertical) Pagination PopoverPlanned Progress stepper Scheme toggle Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed OverviewColor PalettesCustomizingDevelopers All PatternsAccordionCall to ActionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile All Personalization PatternsAnnouncement FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers Design/code status Release notes Get support

Surface

OverviewStyleGuidelinesCodeDemos
ImportingUsagerh-surfaceImportingUsagerh-surface

Importing

Add rh-surface to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-surface/rh-surface.js';
</script>
Copy to Clipboard Wrap lines

To learn more about installing RHDS elements on your site using an import map read our getting started docs.

Usage 

<rh-surface id="surface" color-palette="darkest">
  <rh-blockquote align="inline-start" size="default">
    <p>Surface is used to provide a theme to children</p>
  </rh-blockquote>
  <rh-spinner size="lg">Loading...</rh-spinner>
  <rh-tag color="green">Sold</rh-tag>
</rh-surface>

<style>
#surface {
  display: grid;
  grid-auto-columns: 1fr;
  grid-auto-flow: column;
  justify-items: center;
  align-items: center;
  padding: var(--rh-space-xl);
}
</style>

<script type="module">
  import '@rhds/elements/rh-surface/rh-surface.js';
  import '@rhds/elements/rh-blockquote/rh-blockquote.js';
  import '@rhds/elements/rh-spinner/rh-spinner.js';
  import '@rhds/elements/rh-tag/rh-tag.js';
</script>
Copy to Clipboard Wrap lines

rh-surface

A surface provides color context to descendants via color-palette. Authors must set a color-palette and should use surface only when containers like rh-card are not appropriate. Each palette provides WCAG-compliant contrast when using the default theme. Surface is non-interactive: Tab and focus pass through to focusable children. Users of AT perceive no additional semantics from this element.

Slots 1

Slot Name Summary Description
[default]

Accepts any content.
Note: [default] unnamed slots do not have a slot="name" attribute.

Attributes 1

Attribute DOM Property Description Type Default
color-palette colorPalette

Sets the color palette, which controls the element's background color and propagates accessible text and interactive colors to descendants. Accepted values are lightest, lighter, light, dark, darker, and darkest. Surface always overrides the parent's color context. Your theme will influence these colors so check there first if you are seeing inconsistencies. See CSS Custom Properties for default values.

 
'light' | 'lighter' | 'lightest' | 'dark' | 'darker' | 'darkest'
 
unknown

Methods 0

None

Events 0

None

CSS Shadow Parts 0

None

CSS Custom Properties 0

None

Design Tokens 2

Token Description Copy
--rh-color-text-primary

Primary text color
--rh-color-surface

Surface background color

Other libraries

To learn more about our other libraries, visit the getting started page.
Edit this page on GitHub
© 2026 Red Hat Deploys by Netlify