funkwhale/front/ui-docs/components/ui/card.md

<script setup lang="ts">
  import Button from '~/components/ui/Button.vue'
  import Card from '~/components/ui/Card.vue'
  import Layout from '~/components/ui/Layout.vue'
  import OptionsButton from '~/components/ui/button/Options.vue'
  import Spacer from '~/components/ui/layout/Spacer.vue'
  // import { useRoute } from 'vue-router'

  const alert = ( message: string ) => window.alert(message)
  // const router = useRouter()
</script>

# Card

Funkwhale cards are used to contain textual information, links, and interactive buttons. You can use these to create visually pleasing links to content or to present information.

::: details Parameters

#### Props

```ts
interface Props extends Partial<RouterLinkProps> {
  title: string;
  category?: true | "h1" | "h2" | "h3" | "h4" | "h5";
  color?: Pastel;
  image?: string | { src: string; style?: "withPadding" };
  tags?: string[];
}
```

You have to set a title for the card by passing a `title` prop.

#### Style

- Set `--width` on the element to override the default Card width.

:::

<Layout grid :column-width=290>

```vue-html
<Card title="For music lovers">
  Access your personal music
  collection from anywhere.
  Funkwhale gives you access to
  publication and sharing tools
  you can use to promote that
  your content across the web.
</Card>
```

<div class="preview">
<Card title="For music lovers">
  Access your personal music collection from anywhere. Funkwhale gives you access to publication and sharing tools that you can use to promote your content across the web.
</Card>
</div>

</Layout>

## Card as a Link

Add a `:to` prop, either containing an external link (`"https://..."`) or a Vue Router destination:

<Layout flex>

```ts
<Card small title="Link"
  :to="{name: 'library.albums.detail', params: {id: album.id}}"
/>
```

<Layout class="preview">
<Card small title="Link"
  :to="{name: 'library.albums.detail', params: {id: 1}}"
/>
</Layout>
</Layout>

## Card as a Category header

Category cards are basic cards that contain only a title. To create a category card, pass a `category` prop.

<Layout flex>

```vue-html{1}
<Card category
  title="Example Translations"
/>
```

<div class="preview">
  <Card category
  title="Example Translations"
  />
</div>
</Layout>

## Add an Image

Pass an image source to the `image` prop or set both `image.src` and `image.style` by passing an object.

<Layout :columnWidth="200" grid>

```vue-html{4,11-12}
<Card
  style="--width:208px"
  title="For music lovers"
  image="https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb">
/>


<Card
  style="--width:208px"
  title="For music lovers"
  :image="{ src:'https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb',
            style:'withPadding' }"
/>
```

<Layout stack class="preview">
  <Card
    title="For music lovers"
    style="--width:208px"
    image="https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb"
  />

<Card
    title="For music lovers"
    style="--width:208px"
    :image="{ src:'https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb',
              style:'withPadding' }"
  />
</Layout>
</Layout>

## Add an Icon

<Layout columns>

```vue-html{4}
<Card
  title="Uploading..."
  image="https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb"
  icon="bi-cloud-arrow-up-fill"
/>
```

<Layout class="preview">
<Card
  title="Uploading..."
  image="https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb"
  icon="bi-cloud-arrow-up-fill"
/>
</Layout>
</Layout>

You can combine this prop with any other prop configuration. If you combine it with an image, keep an eye on the contrast ratio between the icon color and the image.

## Add an Alert

```vue-html{2-4}
<Card title="Your Collection">
  <template #alert>
    Please annotate all items with the required metadata.
  </template>
</Card>
```

<div class="preview">
<Card title="Your Collection">
  <template #alert>Please annotate all items with the required metadata.</template>
</Card>
</div>

## Add a Footer

Items in this region are secondary and will be displayed smaller than the main content.

```vue-html{3-9}
<Card title="My items">
  <template #alert> There are no items in this list </template>
  <template #footer>
    <Button variant="outline" icon="bi-upload" @click="alert('Uploaded. Press OK!')">
      Upload
    </Button>
    <Spacer style="flex-grow: 1" />
    <OptionsButton />
  </template>
</Card>
```

<div class="preview">
<Card title="My items">

<template #alert>There are no items in this list
</template>

<template #footer>
<Button variant="outline" icon="bi-upload" @click="alert('Uploaded. Press OK!')">Upload</Button>
<Spacer style="flex-grow: 1" />
<OptionsButton />
</template>

</Card>
</div>

## Add an Action

Large Buttons or links at the bottom edge of the card serve as Call-to-Actions (CTA).

```vue-html{3-6}
<Card title="Join an existing pod">
  The easiest way to get started with Funkwhale is to register an account on a public pod.
  <template #action>
    <Button @click="alert('Open the pod picker')">Action!
    </Button>
  </template>
</Card>
```

<div class="preview">
  <Card title="Join an existing pod">
    The easiest way to get started with Funkwhale is to register an account on a public pod.
    <template #action>
      <Button @click="alert('Open the pod picker')">Action!
      </Button>
    </template>
  </Card>
</div>

If there are multiple actions, they will be presented in a row:

```vue-html{4,7}
<Card title="Delete this pod?">
  You cannot undo this action.
  <template #action>
    <Button style="justify-content: flex-start;" icon="bi-chevron-left" color="secondary" variant="ghost">
      Back
    </Button>
    <Button style="flex-grow:0;" color="destructive" @click="alert('Deleted')">
      Delete
    </Button>
  </template>
</Card>
```

<div class="preview">
  <Card title="Delete this pod?">
    You cannot undo this action.
    <template #action>
      <Button style="width:50%; justify-content: flex-start;" icon="bi-chevron-left" color="secondary" variant="ghost">
        Back
      </Button>
      <Button style="width:50%" color="destructive" @click="alert('Deleted')">
        Delete
      </Button>
    </template>
  </Card>
</div>

## Add Tags

You can include tags on a card by adding a list of `tags`. These are rendered as [pills](./pill.md).

```vue-html{3}
<Card
  title="For music lovers"
  :tags="['rock', 'folk', 'punk']"
>
  Access your personal music collection from anywhere. Funkwhale gives you access to publication and sharing tools that you can use to promote your content across the web.
</Card>
```

<div class="preview">
<Card
title="For music lovers"
:tags="['rock', 'folk', 'punk']">
Access your personal music collection from anywhere. Funkwhale gives you access to publication and sharing tools that you can use to promote your content across the web.
</Card></div>