# Card

> Use cards to display content in a box

The `<Card>` component groups related content and actions in a visually distinct box. Optional elements include icons, titles, and links.

You can use individual cards or arrange multiple cards in a responsive grid layout using the `<CardGroup>` component. Card groups are useful for organizing feature lists, navigation options, or step-by-step guides.

## Usage

<div>
  <div>
    <Card title="Watering guide" icon="regular droplet" href="/learn/docs/writing-content/components/cards">
      The icon field references a Font Awesome icon.
    </Card>
  </div>
</div>

```jsx Markdown
<Card 
    title="Watering guide" 
    icon="regular droplet" 
    href="/learn/docs/writing-content/components/cards"
>
    The icon field references a Font Awesome icon.
</Card>
```

## Variants

### Group of cards

<div>
  <div>
    <CardGroup cols={2}>
      <Card title="Watering" icon="regular droplet" href="/learn/docs/writing-content/components/cards">
        Learn how to water your plants
      </Card>

      <Card title="Sunlight" icon="regular sun" href="/learn/docs/writing-content/components/cards">
        Understand sunlight requirements for different plants
      </Card>

      <Card title="Soil" icon="regular seedling" href="/learn/docs/writing-content/components/cards">
        Choose the right soil for optimal plant growth
      </Card>

      <Card title="Fertilizer" icon="regular flask" href="/learn/docs/writing-content/components/cards">
        Apply fertilizer to keep your plants healthy
      </Card>
    </CardGroup>
  </div>
</div>

```jsx Markdown
<CardGroup cols={2}>
  <Card 
    title="Watering" 
    icon="regular droplet" 
    href="/learn/docs/writing-content/components/cards"
  >
    Learn how to water your plants
  </Card>
  <Card 
    title="Sunlight" 
    icon="regular sun" 
    href="/learn/docs/writing-content/components/cards"
  >
    Understand sunlight requirements for different plants
  </Card>
  <Card 
    title="Soil" 
    icon="regular seedling" 
    href="/learn/docs/writing-content/components/cards"
  >
    Choose the right soil for optimal plant growth
  </Card>
  <Card 
    title="Fertilizer" 
    icon="regular flask" 
    href="/learn/docs/writing-content/components/cards"
  >
    Apply fertilizer to keep your plants healthy
  </Card>
</CardGroup>
```

### Custom icon

You can use a custom icon by passing an image tag or a relative path to an SVG file.

<div>
  <Card title="Plant care" icon={<img src="https://images.unsplash.com/photo-1466781783364-36c955e42a7f?w=100" alt="Plant icon"/>} href="/learn/docs/writing-content/components/cards">
    Pass in an image tag to use a custom icon.
  </Card>
</div>

```jsx Markdown
<Card 
    title="Plant care" 
    icon={<img src="https://images.unsplash.com/photo-1466781783364-36c955e42a7f?w=100" alt="Plant icon"/>} 
    href="/learn/docs/writing-content/components/cards"
>
    Pass in an image tag to use a custom icon.
</Card>
```

To use a relative path to an SVG file stored in your project:

```jsx Markdown
<Card 
    title="Fern species" 
    icon="./images/fern-leaf.svg"
    href="/learn/docs/writing-content/components/cards"
>
    Use a relative path to reference an SVG file in your project.
</Card>
```

### Custom icon position

<div>
  <Card title="Location" icon="regular globe" iconPosition="left">
    You can set the icon position as `left` or `top`.
  </Card>
</div>

```jsx Markdown
<Card 
    title="Location" 
    icon="regular globe" 
    iconPosition="left"
>
    You can set the icon position as `left` or `top`.
</Card>
```

### Custom icon size

<div>
  <Card title="Size" icon="regular globe" iconSize={10}>
    The icon size is calculated as `iconSize * 4` pixels. For a `40px` icon, set `iconSize` to `10` (10 \* 4 = 40px).
  </Card>
</div>

```jsx Markdown wordWrap
<Card
    title="Size"
    icon="regular globe"
    iconSize={10}
>
    The icon size is calculated as `iconSize * 4` pixels. For a `40px` icon, set `iconSize` to `10` (10 * 4 = 40px).
</Card>
```

### Images

Cards support displaying images alongside content. The image automatically resizes to fit the card dimensions, so you typically don't need to specify `imageWidth` or `imageHeight` unless you want to override the default behavior.

<div>
  <Card title="Plant care guide" src="https://images.unsplash.com/photo-1466781783364-36c955e42a7f" imagePosition="left">
    Display an image alongside your card content. The image automatically scales to fit the card.
  </Card>
</div>

```jsx Markdown
<Card 
    title="Plant care guide" 
    src="https://images.unsplash.com/photo-1466781783364-36c955e42a7f"
    imagePosition="left"
>
    Display an image alongside your card content. The image automatically scales to fit the card.
</Card>
```

<div>
  <Card title="Getting started with plants" src="https://images.unsplash.com/photo-1459411552884-841db9b3cc2a" imagePosition="top">
    Position the image at the top of the card for a banner-style layout.
  </Card>
</div>

```jsx Markdown
<Card
    title="Getting started with plants" 
    src="https://images.unsplash.com/photo-1459411552884-841db9b3cc2a"
    imagePosition="top"
>
    Position the image at the top of the card for a banner-style layout.
</Card>
```

## Properties

### `<CardGroup>` properties

<ParamField path="cols" type="number" required={false} default="2">
  The number of columns to display in the grid
</ParamField>

### `<Card>` properties

<ParamField path="title" type="string">
  The title text to display in the card
</ParamField>

<ParamField path="icon" type="string | img">
  A [Font Awesome](https://fontawesome.com/icons) icon class (e.g. 'brands python'), a relative path to an SVG file (e.g. './images/icon.svg'), or a custom image element
</ParamField>

<ParamField path="href" type="string">
  Optional URL that makes the entire card clickable
</ParamField>

<ParamField path="iconPosition" type="'top' | 'left'" default="top">
  The position of icon relative to the text.
</ParamField>

<ParamField path="iconSize" type="number" default="8">
  Size of the icon (width and height) calculated as `iconSize * 4` pixels (e.g., 6 = 24px × 24px, 8 = 32px × 32px).
</ParamField>

<ParamField path="color" type="string">
  Hex color value for the icon (e.g. `#FF0F00`). Ignored if `lightModeColor` and `darkModeColor` are both set
</ParamField>

<ParamField path="darkModeColor" type="string">
  Hex color value for the icon in dark mode (e.g. `#FF0F00`)
</ParamField>

<ParamField path="lightModeColor" type="string">
  Hex color value for the icon in light mode (e.g. `#FF0F00`)
</ParamField>

<ParamField path="src" type="string">
  URL of the image to display in the card. When set, the card displays the image alongside the content.
</ParamField>

<ParamField path="imagePosition" type="'top' | 'left' | 'right' | 'bottom'" default="top">
  Position of the image relative to the card content. Use `imagePosition` to control the layout.
</ParamField>

<ParamField path="imageWidth" type="string">
  Width of the image (e.g. `200px`, `50%`). Only use if you need to override the default sizing. The image automatically resizes to fit the card by default.
</ParamField>

<ParamField path="imageHeight" type="string">
  Height of the image (e.g. `150px`, `100%`). Only use if you need to override the default sizing. The image automatically resizes to fit the card by default.
</ParamField>