Surface

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

Import

import { AvSurfaceComponent } from '@avesra/angular';

Usage

Surface Content

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

import { Component } from '@angular/core';
import { AvSurfaceComponent } from '@avesra/angular';

@Component({
  selector: 'app-surface-basic-demo',
  imports: [AvSurfaceComponent],
  host: { class: 'block' },
  template: `<div
  av-surface
  variant="default"
  class="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6"
>
  <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>
</div>`,
})
export class SurfaceBasicDemo {}

Anatomy

Apply div[av-surface] and set variant for prominence. Project any content as children.

<div av-surface variant="default">
  <!-- Surface content -->
</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)
transparent — No background, for overlays and custom surfaces

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.

import { Component } from '@angular/core';
import { AvSurfaceComponent } from '@avesra/angular';

@Component({
  selector: 'app-surface-variants-demo',
  imports: [AvSurfaceComponent],
  host: { class: 'block' },
  template: `<div class="flex flex-col gap-4">
  <div class="flex flex-col gap-2">
    <p class="text-sm font-medium text-muted">Default</p>
    <div
      av-surface
      variant="default"
      class="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6"
    >
      <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>
    </div>
  </div>

  <div class="flex flex-col gap-2">
    <p class="text-sm font-medium text-muted">Secondary</p>
    <div
      av-surface
      variant="secondary"
      class="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6"
    >
      <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>
    </div>
  </div>

  <div class="flex flex-col gap-2">
    <p class="text-sm font-medium text-muted">Tertiary</p>
    <div
      av-surface
      variant="tertiary"
      class="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6"
    >
      <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>
    </div>
  </div>

  <div class="flex flex-col gap-2">
    <p class="text-sm font-medium text-muted">Transparent</p>
    <div
      av-surface
      variant="transparent"
      class="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6"
    >
      <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>
    </div>
  </div>
</div>`,
})
export class SurfaceVariantsDemo {}

Usage with Form Components

When using form components inside a Surface, set variant="secondary" on inputs and textareas to apply the lower emphasis variant suitable for surface backgrounds.

import { Component } from '@angular/core';
import { AvInputComponent, AvSurfaceComponent, AvTextareaComponent } from '@avesra/angular';

@Component({
  selector: 'app-surface-with-form-components-demo',
  imports: [AvSurfaceComponent, AvInputComponent, AvTextareaComponent],
  host: { class: 'flex w-full items-center justify-center' },
  template: `<div
  av-surface
  variant="default"
  class="flex w-full max-w-md flex-col gap-3 rounded-3xl p-6"
>
  <input
    av-input
    full-width
    placeholder="Input with secondary variant"
    variant="secondary"
    aria-label="Name"
  />
  <textarea
    av-textarea
    full-width
    placeholder="TextArea with secondary variant"
    variant="secondary"
    aria-label="Message"
    rows="3"
  ></textarea>
</div>`,
})
export class SurfaceWithFormComponentsDemo {}

Styling

Passing Tailwind CSS classes

Pass utility classes on the surface host — div[av-surface].

Billing overview

View invoices and payment methods in one place.

import { Component } from '@angular/core';
import { AvSurfaceComponent } from '@avesra/angular';

@Component({
  selector: 'app-surface-custom-styling-demo',
  imports: [AvSurfaceComponent],
  host: { class: 'block' },
  template: `<div
  av-surface
  variant="default"
  class="w-full max-w-sm rounded-xl border border-accent/15 bg-linear-to-br from-accent/8 via-surface to-surface-secondary p-4"
>
  <h3 class="text-sm font-semibold text-foreground">Billing overview</h3>
  <p class="text-sm text-muted">View invoices and payment methods in one place.</p>
</div>`,
})
export class SurfaceCustomStylingDemo {}

Customizing the component classes

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

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

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

Avesra follows the BEM methodology so component variants and states stay reusable and easy to customize.

CSS Classes

The Surface component uses these CSS classes:

Base Classes

.av-surface — Base surface container

Variant Classes

.av-surface--default — Default surface variant (bg-surface)
.av-surface--secondary — Secondary surface variant (bg-surface-secondary)
.av-surface--tertiary — Tertiary surface variant (bg-surface-tertiary)
.av-surface--transparent — Transparent surface (no background)

API

Props for div[av-surface].

Prop	Type	Default	Description
`variant`	`'transparent' \| 'default' \| 'secondary' \| 'tertiary'`	`'default'`	The visual variant of the surface (div[av-surface]).

Context API

AvSurfaceContext

Child components can inject AvSurfaceContext to read the current surface variant. Prefer { optional: true } when the consumer may render outside a surface.

import { Component, inject } from '@angular/core';
import { AvSurfaceContext } from '@avesra/angular';

@Component({
  selector: 'app-my-component',
  template: `...`,
})
export class MyComponent {
  private readonly surface = inject(AvSurfaceContext, { optional: true });

  // this.surface?.variant() → "transparent" | "default" | "secondary" | "tertiary" | undefined
}