Surface

Container component that provides surface-level styling and context for child components.

Import

import { Surface } from "heroui-solid";

Usage

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70import { Surface } from "heroui-solid"

export function Variants() {
  return (
    <div class="flex flex-col gap-4">
      <div class="flex flex-col gap-2">
        <p class="text-sm font-medium text-muted">Default</p>
        <Surface
          class="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6"
          variant="default"
        >
          <h3 class="text-base font-semibold text-foreground">
            Surface Content
          </h3>
          <p class="text-sm text-muted">
            This is a default surface variant. It uses bg-surface styling.
          </p>
        </Surface>
      </div>

      <div class="flex flex-col gap-2">
        <p class="text-sm font-medium text-muted">Secondary</p>
        <Surface
          class="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6"
          variant="secondary"
        >
          <h3 class="text-base font-semibold text-foreground">
            Surface Content
          </h3>
          <p class="text-sm text-muted">
            This is a secondary surface variant. It uses bg-surface-secondary
            styling.
          </p>
        </Surface>
      </div>

      <div class="flex flex-col gap-2">
        <p class="text-sm font-medium text-muted">Tertiary</p>
        <Surface
          class="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6"
          variant="tertiary"
        >
          <h3 class="text-base font-semibold text-foreground">
            Surface Content
          </h3>
          <p class="text-sm text-muted">
            This is a tertiary surface variant. It uses bg-surface-tertiary
            styling.
          </p>
        </Surface>
      </div>

      <div class="flex flex-col gap-2">
        <p class="text-sm font-medium text-muted">Transparent</p>
        <Surface
          class="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
          variant="transparent"
        >
          <h3 class="text-base font-semibold text-foreground">
            Surface Content
          </h3>
          <p class="text-sm text-muted">
            This is a transparent surface variant. It has no background,
            suitable for overlays and cards with custom backgrounds.
          </p>
        </Surface>
      </div>
    </div>
  )
}

Overview

The Surface component is a semantic container that provides different levels of visual prominence through variants.

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)

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

import { Surface, Input, TextArea } from "heroui-solid";

function App() {
  return (
    <Surface variant="default">
      <Input placeholder="Input with secondary variant" variant="secondary" />
      <TextArea placeholder="TextArea with secondary variant" variant="secondary" />
    </Surface>
  );
}

Card: Flexible content container built on Surface semantics
Fieldset: Group related form controls with legends (not ported yet)

Styling

Passing Tailwind CSS classes

import { Surface } from "heroui-solid";

function CustomSurface() {
  return (
    <Surface class="rounded-2xl p-8 shadow-lg" variant="secondary">
      <h2>Custom Styled Surface</h2>
      <p>Content goes here</p>
    </Surface>
  );
}

Customizing the component classes

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

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 Props

Prop	Type	Default	Description
`variant`	`"transparent" \| "default" \| "secondary" \| "tertiary"`	`"default"`	The visual variant of the surface
`class`	`string`	-	Additional CSS classes
`children`	`JSX.Element`	-	The surface content
`as`	`ValidComponent`	`"div"`	Overrides the default DOM element (Kobalte polymorphic)

Context API

SurfaceContext

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

import { useContext } from "solid-js";
import { SurfaceContext } from "heroui-solid";

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

Differences from HeroUI React

Use class instead of className; the element type is overridden with Kobalte's polymorphic as prop instead of React's render prop.
Read surface.variant off the context object inside JSX (a getter keeps it reactive) instead of destructuring it.

Last updated: 7/19/26, 3:27 AM