# md-card
**A container for related content and actions about a single subject.** Three
variants (elevated, filled, outlined), an optional interactive mode with ripple
and state layers, and an optional pointer-drag gesture that reports movement but
never reorders anything itself.
> Setup, theming, density and i18n are configured once for the whole library —
> see the library-wide specification, shipped next to these manuals as
> `main-llm.md` at the root of the `@awc-ui/core` package.
---
## When to use
- Grouping **content and actions about one subject** — a product, an article, a
contact — especially when several appear together as a collection.
- An entry point into a detail view (`interactive`).
- Reorderable tiles, where you own the reorder logic (`drag-enabled`).
## When NOT to use
| Situation | Use instead |
|---|---|
| A vertical list of records | `md-list` + `md-list-item` |
| A blocking decision | `md-dialog` |
| A transient message | `md-snackbar` |
| Content that spacing or a heading would organise better | Nothing — M3 warns against forcing content into cards |
| Collapsible sections | `md-accordion` |
| A single action | `md-button` |
## Decision cues
| Need | Setting |
|---|---|
| Default, subtly raised | `variant="elevated"` (default) |
| Flat, tonal surface | `variant="filled"` |
| Defined edge, no shadow | `variant="outlined"` |
| Whole card is one control | `interactive` (+ `mdClick`) |
| Interactive, but no ripple | `interactive ripple="false"` |
| Reorderable | `drag-enabled` (+ `mdDragStart` / `mdDragMove` / `mdDragEnd`) |
| Fill its grid cell | `full-width` / `full-height` |
| Cap a fluid card | `full-width` + `--md-card-max-width` |
## API contract
```html
interactive
drag-enabled
disabled
soft-disabled
ripple="true|false"
full-width
full-height
density="-1|-2|-3|-4"
>
Headline
Supporting text
```
**Events** — `mdClick` (`CustomEvent`), `mdDragStart` /
`mdDragMove` / `mdDragEnd` (`CustomEvent`). All four are
default Stencil events, so they bubble and cross shadow boundaries.
`MdCardDragDetail` is `{ clientX, clientY, offsetX, offsetY, startX, startY }`,
where `offsetX`/`offsetY` are the distance travelled from the drag start point.
**Methods** — none.
**Slots** — one unnamed default slot. There are no named slots: the card is a
container, not a template, so media, headline and actions are your markup. The
host is `display: flex; flex-direction: column`, so slotted children stack and
are separated by `--md-card-gap`.
**Parts** — `state-layer` (rendered only when `interactive` or `drag-enabled`),
`outline` (rendered only for `variant="outlined"`).
### Behavioral contract worth knowing
- `mdClick` fires **only when `interactive` is set**. Without it the click
handler returns immediately, so a plain card is inert.
- **The card decides its own `role`.** When `interactive` and the slotted
content holds no focusable controls, the host sets `role="button"` and
`tabindex="0"`, and Enter/Space activate it. Do not set `role` yourself —
the render pass writes the attribute and will overwrite yours.
- **Focusable content demotes the card.** If the slotted content contains a
focusable control (native `a[href]`, `button`, `input`, `select`,
`textarea`, `[contenteditable]`, widget ARIA roles, or a library tag such as
`md-button`, `md-icon-button`, `md-checkbox`, `md-switch`, `md-text-field`,
`md-select`, `md-slider`, `md-chip`…), the host drops `role="button"` and
`tabindex` to avoid a `nested-interactive` violation. It still emits
`mdClick` on mouse click, but there is then **no keyboard path to the card
action** — so either the card is the control, or its children are.
The scan runs before first render and again on `slotchange` and on any
light-DOM mutation, so it stays correct for content added later.
- `disabled` removes the card from the tab order (`tabindex="-1"`) and sets
`pointer-events: none`.
- **`soft-disabled` is focusable but inert — not clickable.** It keeps
`tabindex="0"` and still receives pointer events, but both the click handler
and the keydown handler bail on `disabled || soft-disabled`, so a
`soft-disabled` card emits **no `mdClick`** and does not activate on
Enter / Space. Use it when the card must stay reachable and announceable
(so a screen-reader user can find out why it is unavailable), not when you
still want the action to run. Both flags also block the drag gesture.
- **The two flags mute the card differently.** The `disabled` look is gated on
`interactive`: the host only gets its disabled class when
`interactive && (disabled || soft-disabled)`, so `` or
`` keeps its normal colours (the gesture is
still blocked). The `soft-disabled` look is ungated — it comes from a plain
`:host([soft-disabled])` rule — so even a bare ``
renders muted.
- **`drag-enabled` reports the gesture; it does not reorder anything.** The
drag starts only after the pointer moves 5px (Manhattan distance) with the
primary button held. While dragging, the component writes `transform` and
`z-index: 1000` to the host's inline style and clears both on release, so the
card snaps back to its original position — persisting a new order is yours.
- While dragging the card raises its own elevation (`elevation-4` elevated,
`elevation-3` filled/outlined). You do not need to set elevation by hand.
- A click generated at the end of a drag is suppressed for one animation
frame, so a drag never fires `mdClick`.
- `drag-enabled` also mirrors `aria-grabbed` (`"false"` at rest, `"true"` while
dragging) onto the host.
- The host is `overflow: hidden` — a card never scrolls internally.
---
## Do / Don't
Sourced from [M3 · Cards · Guidelines](https://m3.material.io/components/cards/guidelines).
| ✅ Do | ❌ Don't |
|---|---|
| Show cards together as a collection | Don't force content into cards when spacing, headlines, or dividers would give a simpler hierarchy |
| Expand a card to reveal more information | Don't scroll **within** a card to reveal information |
| On mobile, let a card expand and the page scroll | Don't nest a scroller in a card — two scrollbars is the failure mode |
| Assign at most **one** swipe action to a card | Don't put swipeable content (carousels, pagination) inside a card, and don't let parts detach on swipe |
| Let elevation rise while a card is being moved | Don't let a dragged card bump other elements aside — it floats above everything except app bars and navigation |
| Ensure text over images meets contrast standards | Don't place text directly on a busy image without a bounding shape |
| Keep one subject per card | Don't mix unrelated content in one card |
---
## Patterns
```html
Weekly report
Generated 2 hours ago.
Open
Share
```
```html
Weekly report
Generated 2 hours ago.
```
```html
Tile A
```
```html
One
Two
```
## Anti-patterns
| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| `interactive` card that also holds `md-button`s | Pick one: clickable card **or** card with actions | The host detects the focusable children and drops `role="button"`/`tabindex`, so the card action becomes mouse-only. |
| `` | Let the card set its own `role` | Render writes `role="button"` on the host and overwrites the attribute. |
| Listening for `mdClick` on a card without `interactive` | Add `interactive` | The click handler returns early when `interactive` is false. |
| Setting `--md-card-container-elevation` on drag start | Nothing — the dragged state raises elevation itself | The `dragged` state rule sets the elevation directly and wins over the custom property. |
| `--md-card-container-elevation: 3` | `--md-card-container-elevation: var(--md-sys-elevation-3)` | The property is a `box-shadow` value, not an elevation number. |
| Expecting `drag-enabled` to reorder or to leave the card where it was dropped | Handle `mdDragEnd` and commit the order yourself | The component clears the inline `transform` on release. |
| `overflow: auto` on a card | Let the page scroll, or expand the card | The host is `overflow: hidden`; M3 says cards don't scroll internally. |
| Looking for `headline` / `media` / `actions` slots | Compose freely in the default slot | The card has no named slots. |
| `` | Slot an `