Card

Card is a versatile container that groups related content with a visual boundary, typically featuring background color, padding, borders, and rounded corners. It's ideal for organizing information, creating sections, and establishing visual hierarchy in your interface.

Key features:

Pre-styled elements: Built-in support for title, subtitle, and avatarUrl properties
Flexible layout: Choose vertical (default) or horizontal orientation
Visual grouping: Automatic styling with background, borders, and spacing
Clickable areas: Supports click events for interactive cards

Using Card

Card is a container; it does not have any explicit properties. You can nest the card's content into the <Card> tag:

<App>
  <Card maxWidth="200px">
    <HStack verticalAlignment="center">
      <Icon name="info" />
      <Text value="Information" variant="strong" />
    </HStack>
    <Text value="This is an example text" />
  </Card>
</App>

Example: using Card

<App>
  <Card maxWidth="200px">
    <HStack verticalAlignment="center">
      <Icon name="info" />
      <Text value="Information" variant="strong" />
    </HStack>
    <Text value="This is an example text" />
  </Card>
</App>

There are also prestyled properties one can make use of, detailed in the Properties section. Prestyled elements always appear above other children.

<App>
  <Card
    avatarUrl="https://i.pravatar.cc/100"
    title="Example Title"
    subtitle="Predefined subtitle"
    maxWidth="300px">
    <HStack verticalAlignment="center">
      <Icon name="info"/>
      This is a card
    </HStack>
  </Card>
</App>

Example: using Card with prestyled elements

<App>
  <Card
    avatarUrl="https://i.pravatar.cc/100"
    title="Example Title"
    subtitle="Predefined subtitle"
    maxWidth="300px">
    <HStack verticalAlignment="center">
      <Icon name="info"/>
      This is a card
    </HStack>
  </Card>
</App>

Behaviors

This component supports the following behaviors:

Behavior	Properties
Animation	`animation`, `animationOptions`
Bookmark	`bookmark`, `bookmarkLevel`, `bookmarkTitle`, `bookmarkOmitFromToc`
Display When	`displayWhen`
Component Label	`label`, `labelPosition`, `labelWidth`, `labelBreak`, `required`, `enabled`, `shrinkToLabel`, `style`, `readOnly`
Tooltip	`tooltip`, `tooltipMarkdown`, `tooltipOptions`
Styling Variant	`variant`

Properties

`avatarSize`

This prop sets the size of the avatar. The default value is sm.

Available values: xs, sm, md, lg

`avatarUrl`

The url for an avarar image. If not specified, but showAvatar is true, Card will show the first letters of the title.

`horizontalAlignment`

default: "start"

Manages the horizontal content alignment for each child element in the Card.

Available values: start (default), center, end

`linkTo`

This optional property wraps the title in a Link component that is clickable to navigate.

`orientation`

default: "vertical"

An optional property that governs the Card's orientation (whether the Card lays out its children in a row or a column). If the orientation is set to horizontal, the Card will display its children in a row, except for its title and subtitle.

Available values:

Value	Description
`horizontal`	The component will fill the available space horizontally
`vertical`	The component will fill the available space vertically (default)

<App>
  <Card title="Example Title" subtitle="Example Subtitle" orientation="horizontal">
    <SpaceFiller />
    <Text>Text child #1</Text>
    <Text>Text child #2</Text>
    <Button label="Button Child" />
  </Card>
</App>

Example: orientation

<App>
  <Card title="Example Title" subtitle="Example Subtitle" orientation="horizontal">
    <SpaceFiller />
    <Text>Text child #1</Text>
    <Text>Text child #2</Text>
    <Button label="Button Child" />
  </Card>
</App>

`showAvatar`

default: false

Indicates whether the avatar should be displayed

Note that in the demo below if the avatarUrl is specified, showAvatar is automatically set to true but can still be hidden.

<App>
  <Card maxWidth="300px" avatarUrl="https://i.pravatar.cc/100" />
  <Card maxWidth="300px" showAvatar="true" title="Example Card" />
  <Card maxWidth="300px" showAvatar="true" />
</App>

Example: showAvatar

<App>
  <Card maxWidth="300px" avatarUrl="https://i.pravatar.cc/100" />
  <Card maxWidth="300px" showAvatar="true" title="Example Card" />
  <Card maxWidth="300px" showAvatar="true" />
</App>

`subtitle`

This prop sets the pre-styled subtitle. If the property is not set, no subtitle is displayed in the Card.

This prop sets the prestyled subtitle.

<App>
  <Card maxWidth="300px" subtitle="Example Subtitle" />
</App>

Example: subtitle

<App>
  <Card maxWidth="300px" subtitle="Example Subtitle" />
</App>

`title`

This prop sets the pre-styled title. If the property is not set, no title is displayed in the Card.

This prop sets the prestyled title.

<App>
  <Card maxWidth="300px" title="Example Title" />
</App>

Example: title

<App>
  <Card maxWidth="300px" title="Example Title" />
</App>

`verticalAlignment`

default: "start"

Manages the vertical content alignment for each child element in the Card.

Available values: start (default), center, end

Events

`click`

This event is triggered when the Card is clicked.

Signature: click(event: MouseEvent): void

event: The mouse event object.

This event is triggered when the Card is clicked.

<App>
  <Card maxWidth="300px" onClick="toast.success('Clicked!')">
    <HStack verticalAlignment="center">
      <Icon name="info" />
      <Text value="Information" variant="strong" />
    </HStack>
    <Text value="This is an example text" />
  </Card>
</App>

Example: click

<App>
  <Card maxWidth="300px" onClick="toast.success('Clicked!')">
    <HStack verticalAlignment="center">
      <Icon name="info" />
      <Text value="Information" variant="strong" />
    </HStack>
    <Text value="This is an example text" />
  </Card>
</App>

`contextMenu`

This event is triggered when the Card is right-clicked (context menu).

Signature: contextMenu(event: MouseEvent): void

event: The mouse event object.

`doubleClick`

This event is triggered when the Card is double-clicked.

Signature: doubleClick(event: MouseEvent): void

event: The mouse event object.

This event is triggered when the Card is double-clicked. When both onClick and onDoubleClick are used together, only the first click of the double-click fires onClick, so onClick is not called twice.

<App>
  <Card maxWidth="300px" onDoubleClick="toast('Double-clicked!')">
    <HStack verticalAlignment="center">
      <Icon name="info" />
      <Text value="Double-click me" variant="strong" />
    </HStack>
    <Text value="This is an example text" />
  </Card>
</App>

Example: doubleClick

<App>
  <Card maxWidth="300px" onDoubleClick="toast('Double-clicked!')">
    <HStack verticalAlignment="center">
      <Icon name="info" />
      <Text value="Double-click me" variant="strong" />
    </HStack>
    <Text value="This is an example text" />
  </Card>
</App>

Exposed Methods

`scrollToBottom`

Scrolls the Card container to the bottom. Works when the Card has an explicit height and overflowY is set to 'scroll'.

Signature: scrollToBottom(behavior?: 'auto' | 'instant' | 'smooth'): void

`scrollToEnd`

Scrolls the Card container to the end (right in LTR, left in RTL). Works when the Card has an explicit width and overflowX is set to 'scroll'.

Signature: scrollToEnd(behavior?: 'auto' | 'instant' | 'smooth'): void

`scrollToStart`

Scrolls the Card container to the start (left in LTR, right in RTL). Works when the Card has an explicit width and overflowX is set to 'scroll'.

Signature: scrollToStart(behavior?: 'auto' | 'instant' | 'smooth'): void

`scrollToTop`

Scrolls the Card container to the top. Works when the Card has an explicit height and overflowY is set to 'scroll'.

Signature: scrollToTop(behavior?: 'auto' | 'instant' | 'smooth'): void

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

avatar: The avatar displayed within the card, if any.
subtitle: The subtitle of the card.
title: The title of the card.

Styling

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-Card	$color-surface-raised	$color-surface-raised
backgroundColor-Card--hover	$color-surface-raised	$color-surface-raised
border-Card	1px solid $borderColor	1px solid $borderColor
borderBottom-Card	none	none
borderBottomColor-Card	none	none
borderBottomStyle-Card	none	none
borderBottomWidth-Card	none	none
borderColor-Card	none	none
borderEndEndRadius-Card	none	none
borderEndStartRadius-Card	none	none
borderHorizontal-Card	none	none
borderHorizontalColor-Card	none	none
borderHorizontalStyle-Card	none	none
borderHorizontalWidth-Card	none	none
borderLeft-Card	none	none
borderLeftColor-Card	none	none
borderLeftStyle-Card	none	none
borderLeftWidth-Card	none	none
borderRadius-Card	$borderRadius	$borderRadius
borderRight-Card	none	none
borderRightColor-Card	none	none
borderRightStyle-Card	none	none
borderRightWidth-Card	none	none
borderStartEndRadius-Card	none	none
borderStartStartRadius-Card	none	none
borderStyle-Card	none	none
borderTop-Card	none	none
borderTopColor-Card	none	none
borderTopStyle-Card	none	none
borderTopWidth-Card	none	none
borderVertical-Card	none	none
borderVerticalColor-Card	none	none
borderVerticalStyle-Card	none	none
borderVerticalWidth-Card	none	none
borderWidth-Card	none	none
boxShadow-Card	none	none
gap-avatar-Card	$gap-normal	$gap-normal
gap-Card	var(--stack-gap-default)	var(--stack-gap-default)
gap-title-Card	$gap-none	$gap-none
horizontalAlignment-title-Card	none	none
padding-Card	$space-4	$space-4
paddingBottom-Card	none	none
paddingHorizontal-Card	none	none
paddingLeft-Card	none	none
paddingRight-Card	none	none
paddingTop-Card	none	none
paddingVertical-Card	none	none
verticalAlignment-title-Card	center	center

Variable Explanations

Theme Variable	Description
`backgroundColor-Card--hover`	The background color of the Card when hovered.
`gap-Card`	The gap between the component's children.
`gap-title-Card`	The gap between the title and the subtitle
`gap-avatar-Card`	The gap between the avatar and the title panel
`horizontalAlignment-title-Card`	The horizontal alignment of panel with the title and subtitle
`verticalAlignment-title-Card`	The vertical alignment of the title and subtitle to the avatar