Usage

import { Surface } from '@heroui/react';

Surface Content

This is a default surface variant. It uses bg-surface styling.

Examples

Variants

Surface comes in semantic variants that describe their prominence level:

default - Standard surface appearance (bg-surface)
secondary - Medium prominence (bg-surface-secondary)
tertiary - Higher prominence (bg-surface-tertiary)

Default

Surface Content

This is a default surface variant. It uses bg-surface styling.

Secondary

Surface Content

This is a secondary surface variant. It uses bg-surface-secondary styling.

Tertiary

Surface Content

This is a tertiary surface variant. It uses bg-surface-tertiary styling.

Transparent

Surface Content

This is a transparent surface variant. It has no background, suitable for overlays and cards with custom backgrounds.

With Form Components

When using form components inside a Surface, use the variant="secondary" prop to apply the lower emphasis variant suitable for surface backgrounds.

Customization

Tailwind CSS

Billing overview

View invoices and payment methods in one place.

Global CSS

To customize the Surface component classes, you can use the @layer components directive. Learn more.

@layer components {
  .surface {
    @apply rounded-2xl border border-border;
  }

  .surface--secondary {
    @apply bg-gradient-to-br from-blue-50 to-purple-50;
  }
}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Surface component uses these CSS classes (View source styles):

Base Classes

.surface - Base surface container

Variant Classes

.surface--default - Default surface variant (bg-surface)
.surface--secondary - Secondary surface variant (bg-surface-secondary)
.surface--tertiary - Tertiary surface variant (bg-surface-tertiary)

API Reference

Surface

Prop	Type	Default	Description
`variant`	`"transparent" \| "default" \| "secondary" \| "tertiary"`	`"default"`	The visual variant of the surface
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode`	-	The surface content

Context API

SurfaceContext

Child components can access the Surface context to get the current variant:

import { useContext } from 'react';
import { SurfaceContext } from '@heroui/react';

function MyComponent() {
  const { variant } = useContext(SurfaceContext);
  // variant will be "transparent" | "default" | "secondary" | "tertiary" | undefined
}