Support displaying an icon in <LinkCard>

[bugzpodder]

What version of starlight are you using?

latest

What is your idea?

It seems Card supports icon prop but LinkCard doesn't?

Maybe we should combine Card and LinkedCard?

Why is this feature necessary?

I think it's common to have a LinkedCard with an icon?

Do you have examples of this feature in other projects?

https://bugzpodder.github.io/pysandbox/ (I have a LinkedCard but no icon)

would it look good with this green icon?

Participation

• I am willing to submit a pull request for this issue.

[jsparkdev]

The LinkCard component doesn't seem to support icon insertion.

How about using the <a> tag within the Card component instead of LinkCard?

[lschierer]

You can do that, but the link target ends up only being the elements inside the card, whereas with LinkCard, the entire card acts like a button. The user experience is very different.

[AutonomousCat]

+1
I feel like the default arrow icon of a LinkCard sorta symbolizes it goes to a page in the same website (i.e, pointing to somewhere else on the same site). I'd like to replace it with the universal symbol for an external website (you know, the square-ish window one).

[ehakan]

Would like to be able to this as well. I like using LinkCard for links that need to be "in your face", and those usually link to other repositories, external documentation.

[kmalloy24]

I ended up copying the component locally and using type assertions for the icon names I wanted (otherwise you get a TS build error)

index.astro

import IconLinkCard from "../components/IconLinkCard.astro";

 <IconLinkCard
  title="Starlight"
  href="https://starlight.astro.build/"
  target="_blank"
  icon="external"
  iconSize="1.333em"
  />

IconLinkCard.astro

---
import { Icon } from '@astrojs/starlight/components';
import type { HTMLAttributes } from 'astro/types';

interface Props extends Omit<HTMLAttributes<'a'>, 'title'> {
	title: string;
	description?: string;
	icon?: string;
	iconColor?: string;
	iconSize?: string;
}

const { title, description, icon, iconColor, iconSize, ...attributes } = Astro.props;
---

<div class="sl-link-card">
	<span class="sl-flex stack">
		<a {...attributes}>
			<span class="title" set:html={title} />
		</a>
		{description && <span class="description" set:html={description} />}
	</span>
    {icon && <Icon name={icon as "external" | "star" | "rocket"} color={iconColor} size={iconSize} />}
</div>

<style>
	.sl-link-card {
		display: grid;
		grid-template-columns: 1fr auto;
		gap: 0.5rem;
		border: 1px solid var(--sl-color-gray-5);
		border-radius: 0.5rem;
		padding: 1rem;
		box-shadow: var(--sl-shadow-sm);
		position: relative;
	}

	a {
		text-decoration: none;
		line-height: var(--sl-line-height-headings);
	}

	/* a11y fix for https://github.com/withastro/starlight/issues/487 */
	a::before {
		content: '';
		position: absolute;
		inset: 0;
	}

	.stack {
		flex-direction: column;
		gap: 0.5rem;
	}

	.title {
		color: var(--sl-color-white);
		font-weight: 600;
		font-size: var(--sl-text-lg);
	}

	.description {
		color: var(--sl-color-gray-3);
		line-height: 1.5;
	}

	.icon {
		color: var(--sl-color-gray-3);
	}

	/* Hover state */
	.sl-link-card:hover {
		background: var(--sl-color-gray-7, var(--sl-color-gray-6));
		border-color: var(--sl-color-gray-2);
	}

	.sl-link-card:hover .icon {
		color: var(--sl-color-white);
	}
</style>

[almereyda]

Cobbling together from the previous example, https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Card.astro and https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/LinkCard.astro, I have come up with the following:

• cards.mdx

---
title: Cards
---

import { Card, CardGrid } from '@astrojs/starlight/components';
import IconLinkCard from "@components/IconLinkCard.astro";

## Activities

<CardGrid>
	<IconLinkCard
	 title="Product"
	 href="/activities/#product"
	 icon="puzzle"
	>
	  What this is.
	</IconLinkCard>
	<IconLinkCard
	 title="Development"
	 href="/activities/#development"
	 icon="pencil"
	>
	 How it's made.
	</IconLinkCard>

	<IconLinkCard
	 title="Help"
	 href="/activities/#help"
	 icon="error"
	>
	  Something is wrong.
	</IconLinkCard>
	<IconLinkCard
	 title="Contact"
	 href="/activities/#contact"
	 icon="open-book"
	>
	 People, everywhere.
	</IconLinkCard>
</CardGrid>

• IconLinkCard.astro

---
import { Icon } from '@astrojs/starlight/components';
import type { HTMLAttributes } from 'astro/types';

interface Props extends Omit<HTMLAttributes<'a'>, 'title'> {
	icon?: keyof typeof Icon;
	title: string;
}

const { icon, title, ...attributes } = Astro.props;
---

<article class="icon-link-card sl-flex">
    <a {...attributes}>
        <p class="title sl-flex">
            {icon && <Icon name={icon} class="icon" size="1.5em" />}
    		<span class="title" set:html={title} />
    		{icon && <Icon name="right-arrow" size="1.5em" class="rtl:flip" />}
        </p>
    </a>
    <div class="body"><slot /></div>
</article>

<style>
	.icon-link-card {
		--sl-card-border: var(--sl-color-purple);
		--sl-card-bg: var(--sl-color-purple-low);
		border: 1px solid var(--sl-color-gray-5);
		background-color: var(--sl-color-black);
		padding: clamp(1rem, calc(0.125rem + 3vw), 2.5rem);
		flex-direction: column;
		gap: clamp(0.5rem, calc(0.125rem + 1vw), 1rem);
	}

	.icon-link-card:nth-child(4n + 1) {
		--sl-card-border: var(--sl-color-orange);
		--sl-card-bg: var(--sl-color-orange-low);
	}
	.icon-link-card:nth-child(4n + 3) {
		--sl-card-border: var(--sl-color-green);
		--sl-card-bg: var(--sl-color-green-low);
	}
	.icon-link-card:nth-child(4n + 4) {
		--sl-card-border: var(--sl-color-red);
		--sl-card-bg: var(--sl-color-red-low);
	}
	.icon-link-card:nth-child(4n + 5) {
		--sl-card-border: var(--sl-color-blue);
		--sl-card-bg: var(--sl-color-blue-low);
	}

	a {
		text-decoration: none;
		line-height: var(--sl-line-height-headings);
	}

	.title {
		font-weight: 600;
		font-size: var(--sl-text-h4);
		color: var(--sl-color-white);
		line-height: var(--sl-line-height-headings);
		gap: 1rem;
		align-items: center;
	}

	.icon-link-card .icon {
		border: 1px solid var(--sl-card-border);
		background-color: var(--sl-card-bg);
		padding: 0.2em;
		border-radius: 0.25rem;
	}
	.icon-link-card .body {
		margin: 0;
		font-size: clamp(var(--sl-text-sm), calc(0.5rem + 1vw), var(--sl-text-body));
	}

	/* Hover state */
	.icon-link-card:hover {
		background: var(--sl-color-gray-7, var(--sl-color-gray-6));
		border-color: var(--sl-color-gray-2);
	}

	.icon-link-card:hover .icon {
		color: var(--sl-color-white);
	}
</style>

I wanted less configurability for the icon details. Surprisingly a size of 1.5em had to be chosen to have it displayed at equal size with <Card /> icons. The arrows also display at alternating sizes in the grid, but I don't know why.

Is this semantic enough for screen readers, with regards to #487?