> Part of the [Tangram component index](/docs/components/index.md). Use the index to find other components.

# Card (Tangram 2)

A surface that groups related content, with a background, a corner radius and an optional border. The card projects your content with no wrapper, no padding and no slots, so the layout inside is yours.

It has two forms — the `tg2Card` attribute and the `<tg2-card>` element — and the host element decides which to use:

- **The card is the link or button.** Put `tg2Card` on the `<a>` or `<button>`, so the card gets native semantics, focus and its interactive state for free. The component warns in dev mode if it finds `<tg2-card>` nested inside one.
- **The card is a static container.** Use `<tg2-card>`. Links and buttons inside the card do not change this; only the host element counts.

`<div tg2Card>` renders identically to `<tg2-card>`. Reach for it only when the `<div>` is already [interactive](#interactive); write `<tg2-card>` for every other static container.

```html
<a
    tg2Card
    routerLink="/listing/123">
    Content
</a>
<button
    tg2Card
    type="button">
    Content
</button>
<tg2-card
    radius="large"
    background="grey"
    bordered>
    Content
</tg2-card>
```

Angular cannot interpolate a tag name, so a template that picks its host conditionally writes one host per branch, each following the rules above. Where the branches render the same content, share it through an `<ng-template>`:

```html
@if (card().href) {
<a
    tg2Card
    [routerLink]="card().href">
    <ng-container *ngTemplateOutlet="content" />
</a>
} @else {
<tg2-card>
    <ng-container *ngTemplateOutlet="content" />
</tg2-card>
}

<ng-template #content>...</ng-template>
```

## Radius

- `small`: 4px.
- `medium`: 8px. This is the default.
- `large`: 16px.
- `extra-large`: 20px.

With `theme="tg-light"` or `"tg-dark"`, the same values give the legacy card radii: 0, 6px, 8px and 16px. The default is then `large` (8px), so an unmigrated page keeps the legacy card corner.

## Clipping

The card clips its content to its radius with `overflow: hidden`, on every host. A dropdown, tooltip or popover that must go outside the card edges needs an `overflow: visible` override on the host.

## Background

- `white`: the default.
- `grey`: a tg2 surface only. With `theme="tg-light"` or `"tg-dark"`, it gives the same colour as `white`.

## Photos

Put a real `<img>` inside the card. The card radius clips it.

Do not use a CSS `background-image`, and do not use `tg-aspect-ratio`. An `<img>` gets `srcset`, the preload path and a real `alt`.

```html
<a
    tg2Card
    radius="medium"
    [routerLink]="listing.url">
    <img
        class="listing-card__photo"
        [src]="listing.photoUrl"
        alt="" />
    <div class="listing-card__body">{{ listing.title }}</div>
</a>
```

```scss
.listing-card__photo {
    display: block;
    width: 100%;
    aspect-ratio: 4 / 3;
    object-fit: cover;
}
```

## Bordered

`bordered` adds a 1px border.

## Interactive

A card on an `<a>` or a `<button>` is interactive automatically, because the component reads the host's tag name. It gets hover and press states.

A `<div>` cannot be detected that way, so if you have given one `role`, `tabindex` and keyboard handlers of its own, set `interactive` to apply the same states. Reach for a real `<button>` or `<a>` first: it gives you focus, keyboard activation and semantics without writing any of that.

```html
<div
    tg2Card
    interactive
    bordered
    role="button"
    tabindex="0"
    (click)="toggleLiked()"
    (keydown.enter)="toggleLiked()"
    (keydown.space)="$event.preventDefault(); toggleLiked()">
    {{ liked() ? 'Liked' : 'Like' }}
</div>
```

## Dark themes

Do not use `theme="tg2-dark"` or `"tg-dark"`. Design has not reviewed dark mode. It is a work in progress.

<!-- generated:api:start -->
<!-- Generated from tg2-card.component.ts by npm run docs:components. Do not edit by hand. -->

## API

Selector: `tg2-card, [tg2Card]`. Import `Tg2CardComponent` from `@trademe/tangram`.

Experimental: the API can change in a minor release.

### Inputs

- `radius`: `small` | `medium` | `large` | `extra-large`.
- `background`: `white` | `grey`. Default `white`.
- `bordered`: `boolean`. Default `false`.
- `interactive`: `boolean`. Default `false`.
- `theme`: `tg2-light` | `tg2-dark` | `tg-light` | `tg-dark`. Default `tg2-light`.

### Content slots

- Default content

<!-- generated:api:end -->
