# Card (w-card)

## Description

Card is a layout component used for grouping interactive content areas on a page.

[Warp component reference](https://warp-ds.github.io/docs/components/card/frameworks/elements)

## Usage

Card is a layout component used for grouping interactive content areas on a page.

Use `w-card` for listings, summaries, recommendations, or selectable choices where the grouped content should feel like a single object.

The component does not add padding, headings, spacing between children, or semantic structure. Those must be provided by the content inside the card.

### Basic Card

```html
<w-card>
	<div style="padding: 16px;">
		<h3>Apartment in Oslo</h3>
		<p>Bright 3-room apartment with balcony.</p>
	</div>
</w-card>
```

### Visual Treatments

The default card uses an elevated surface. Use `flat` when the card should sit more quietly in the layout.

```html
<w-card>
	<div style="padding: 16px;">
		<h3>Elevated card</h3>
		<p>Use this for cards that need more visual separation.</p>
	</div>
</w-card>

<w-card flat>
	<div style="padding: 16px;">
		<h3>Flat card</h3>
		<p>Use this for dense layouts or cards inside another surface.</p>
	</div>
</w-card>
```

### Selected Cards

Use `selected` when a card represents a selected item or choice.

```html
<w-card selected>
	<div style="padding: 16px;">
		<h3>Standard delivery</h3>
		<p>Delivered in 2-4 business days.</p>
	</div>
</w-card>
```

The `selected` property only controls the card's visual state. Update it from your application state when the selection changes.

### Cards as Links

For navigation, use a native link inside the card and add `data-card-action` to expand its click area to the whole card.

```html
<w-card>
	<div style="padding: 16px;">
		<h3>
			<a href="/listings/123" data-card-action>Apartment in Oslo</a>
		</h3>
		<p>Bright 3-room apartment with balcony.</p>
	</div>
</w-card>
```

When the card has a second independent navigation target, add `data-card-secondary-action` to that link. The secondary action remains independently clickable and should be layered above the primary card action.

```html
<w-card>
	<div style="padding: 16px;">
		<h3>
			<a href="/listings/123" data-card-action>Apartment in Oslo</a>
		</h3>
		<p>Bright 3-room apartment with balcony.</p>
		<a href="/listings/123/contact" data-card-secondary-action>
			Contact seller
		</a>
	</div>
</w-card>
```

Do not use a card action when the card contains buttons, form controls, or other interactive elements that should be part of the same content area. Use the specific control directly instead.

## Accessibility

Card is a visual container. It does not create a heading, landmark, list item, link, button, or other semantic structure for the slotted content.

### Provide Semantic Content

Use semantic HTML inside the card so assistive technologies can understand the content.

```html
<w-card>
	<article style="padding: 16px;" aria-labelledby="listing-heading">
		<h3 id="listing-heading">Apartment in Oslo</h3>
		<p>Bright 3-room apartment with balcony.</p>
	</article>
</w-card>
```

Do not rely on the card surface, border, or selected styling to communicate meaning.

### Selected State

Use `selected` only when the card represents a selected item or choice.

```html
<w-card selected>
	<div style="padding: 16px;">
		<h3>Standard delivery</h3>
		<p>Delivered in 2-4 business days.</p>
	</div>
</w-card>
```

The selected state should also be clear from the surrounding context, such as a group label, heading, or visible text.

### Clickable Cards

Use `clickable` only when the whole card has one action or represents one selectable choice.

```html
<w-card clickable>
	<div style="padding: 16px;">
		<h3>Home delivery</h3>
		<p>Delivered to your door.</p>
	</div>
</w-card>
```

The visible card content should describe what will be selected or activated. Do not put separate links, buttons, form controls, or other interactive elements inside a clickable card.

### Prefer Specific Interactive Elements

If only part of the card is interactive, use the appropriate element for that action.

Use a link for navigation:

```html
<w-card>
	<div style="padding: 16px;">
		<h3><a href="/listings/123">Apartment in Oslo</a></h3>
		<p>Bright 3-room apartment with balcony.</p>
	</div>
</w-card>
```

To make the whole card a link, use a native anchor with `data-card-action` in a non-clickable card.

```html
<w-card>
	<div style="padding: 16px;">
		<h3>
			<a href="/listings/123" data-card-action> Apartment in Oslo </a>
		</h3>
		<p>Bright 3-room apartment with balcony.</p>
	</div>
</w-card>
```

If you need the whole card to be a link and you have additional interactive elements on the card, use `data-card-secondary-action` as well.

```html
<w-card>
	<div style="padding: 16px;">
		<h3>
			<a href="/listings/123" data-card-action> Apartment in Oslo </a>
		</h3>
		<w-button variant="primary" data-card-secondary-action>Contact seller</w-button>
	</div>
</w-card>
```

Use a button for an action on the current page:

```html
<w-card>
	<div style="padding: 16px;">
		<h3>Apartment in Oslo</h3>
		<p>Bright 3-room apartment with balcony.</p>
		<w-button variant="primary">Contact seller</w-button>
	</div>
</w-card>
```

## Examples

### Basic

<elements-example>

```html
<w-card>
  <div style="padding: 16px;">
    <h3>Apartment in Oslo</h3>
    <p>Bright 3-room apartment with balcony.</p>
  </div>
</w-card>
```

</elements-example>

### Flat

<elements-example>

```html
<w-card flat>
  <div style="padding: 16px;">
    <h3>Order summary</h3>
    <p>Review the item price, delivery, and total before continuing.</p>
  </div>
</w-card>
```

</elements-example>

### Selected

<elements-example>

```html
<w-card selected>
  <div style="padding: 16px;">
    <h3>Standard delivery</h3>
    <p>Delivered in 2-4 business days.</p>
  </div>
</w-card>
```

</elements-example>

### Flat Selected

<elements-example>

```html
<w-card flat selected>
  <div style="padding: 16px;">
    <h3>Pickup point</h3>
    <p>Collect the item from a nearby pickup point.</p>
  </div>
</w-card>
```

</elements-example>

### Clickable

<elements-example>

```html
<w-card clickable>
  <div style="padding: 16px;">
    <h3>Home delivery</h3>
    <p>Delivered to your door.</p>
  </div>
</w-card>
```

</elements-example>

## Styling API

Card supports styling through **component tokens** (CSS custom properties with a `--w-c-` prefix) and **parts**.

### Parts

Use `::part(part-name)` from outside the component.

- `base` - the root element of the card
- `border` - the inset border of the card

```css
w-card::part(base) {
	padding: 48px;
	background: rebeccapurple;
	color: cyan;
}
w-card::part(border) {
	border-color: magenta;
	border-width: 8px;
}
```

### Component tokens

Set these on `<w-card>` to override visuals.

```css
w-card {
    --w-c-card-border-radius: 0px;
}
```

##### Layout and typography

- `--w-c-card-border-radius`
- `--w-c-card-border-width`
- `--w-c-card-border-color`
- `--w-c-card-border-color-active`
- `--w-c-card-border-color-hover`

##### Background

- `--w-c-card-bg`
- `--w-c-card-bg-active`
- `--w-c-card-bg-hover`

##### Shadow

- `--w-c-card-box-shadow`
- `--w-c-card-box-shadow-active`
- `--w-c-card-box-shadow-hover`

## `<w-card>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| clickable | `boolean` | `false` | Whether the whole card is interactive. **Deprecated**: This will be removed in a future version. Use data-card-action attribute on a link or button inside the card instead. |
| flat | `boolean` | `false` | Whether the card uses the flat visual treatment. |
| keypressed (JS only) | `keypressed(e: KeyboardEvent) => void` | `-` | - |
| selected | `boolean` | `false` | Whether the card is visually selected. |

### Property Details

#### clickable

**Deprecated**: This will be removed in a future version. Use data-card-action attribute on a link or button inside the card instead.

Whether the whole card is interactive.

When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.

- Type: `boolean`
- Default: `false`

#### flat

Whether the card uses the flat visual treatment.

Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.

- Type: `boolean`
- Default: `false`

#### keypressed (JS only)



- Type: `keypressed(e: KeyboardEvent) => void`
- Default: `-`

#### selected

Whether the card is visually selected.

Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.

- Type: `boolean`
- Default: `false`