# Surface · HeroUI

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

- Page: https://jiguang132.com/systems/heroui/docs/components/surface
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

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

### Usage


> Example `surface-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/surface


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

```tsx
import { Surface, Input, TextArea } from '@heroui/react';

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


## Styling

### Passing Tailwind CSS classes

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

function CustomSurface() {
  return (
    <Surface
      className="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](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@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](https://getbem.com/) 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](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/surface.css)):

#### 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 |
| `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:

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

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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt