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?

[gxxxr-111]

Hi everyone! I’ve just submitted a PR #3788 to address this. It includes full type safety for icons and parity for both MDX and Markdoc. Feel free to check out the deploy preview!

[gxxxr-111]

Hi everyone! I’ve submitted a PR (#3788) to finally add icon support to LinkCard. I’d love to get your feedback on a design detail.

In my current implementation, the custom icon and the default right arrow coexist (the icon is placed next to the title, while the arrow stays on the right as a navigation signifier). However, there's a suggestion to replace the right arrow with the custom icon when one is provided.

I’d love to hear your thoughts:
Option A (Coexist): Keep the arrow to signify it's a link, and use the icon for content categorization (Current PR).
Option B (Replace): Remove the arrow if a custom icon is provided to make the UI cleaner.
Which one do you prefer?

Personally, I think Option A maintains better consistency with the Card component and Starlight's navigation language.

[trueberryless]

I'd like to add screenshots to better visualize the difference between the options brought up here:

Option A (always add new icon near title):

Option B (replace arrow icon when iconPlacement === 'end'):

As you can see, there is no difference when iconPlacement === 'start', but regarding iconPlacement === 'end' this is a very interesting discussion.

---

My personal opinion is that two icons in one link card is too many, as the card gets overloaded. So my preference is to replace the arrow icon when iconPlacement === 'end' (Option B). Feel free to share your thoughts!

I'm pinning @bugzpodder @AutonomousCat @ehakan @kmalloy24 @lschierer and @almereyda for their opinions as they posted in this discussion already and might be interested in how Starlight implements this.

[VisualEhrmanntraut]

what about separating as preTitleIcon, postTitleIcon, and navigateIcon?

[trueberryless]

what about separating as preTitleIcon, postTitleIcon, and navigateIcon?

I think that's a good idea, we just need to document it well, to avoid confusion. But the attribute names already are pretty meaningful 👍

Wdyt, @gxxxr-111?

[gxxxr-111]

I see where you're coming from, but I think a parameter set of titleIcon, titleIconPlacement, and navigationIcon might be a cleaner approach. Allowing both preTitleIcon and postTitleIcon at once could result in a messy UI.

Another concern is the naming: navigateIcon might confuse users if they pass an icon that doesn't actually signify navigation. Plus, from a codebase perspective, we should probably avoid letting navigationIcon be undefined so that it doesn't look identical to a standard Starlight Card component.

[VisualEhrmanntraut]

About the navigation icon naming, I agree that navigationIcon is more correct.

However, from what I can tell, the introduction of a direction for the icon would only slightly complicate the component code further, where otherwise a simple {preTitleIcon && ...} and {postTitleIcon && ...} would suffice.

Additionally, Starlight is a tool, not a design guideline, and should therefore let the users design their site interface however they see fit: There is legitimate use for my idea, and limiting the functionality because of potential misuse doesn't result in cleaner UI; it just results in those who would use an icon for before and after the title, to copy paste the code of starlight and override the component.

Simplicity and user freedom should be at the forefront of software design.