Skip to content

feat(theme): allow custom icons in DocCard component #11596

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jliermann wants to merge 11 commits into from
Closed

feat(theme): allow custom icons in DocCard component #11596

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
75e9502
feat(theme): Allow custom icon in DocCard component
jliermann Dec 2, 2025
9428b8a
feat(theme): add optional icon property to PropSidebarItemLink type
jliermann Dec 2, 2025
aa5be88
test(theme): dogfooding doc for DocCard component
jliermann Dec 2, 2025
257868b
feat(theme): extend CardLink component to support PNG icons
jliermann Dec 2, 2025
e5b5962
text(theme): add svg to dogfood
jliermann Dec 2, 2025
1f53416
Merge branch 'facebook:main' into main
jliermann Dec 2, 2025
85e693e
feat(theme): improve CardLink logic to support PNG or JPEG icons
jliermann Dec 2, 2025
41e0283
test(theme): test for JPG
jliermann Dec 2, 2025
84ff66d
test(theme): make sure all links work
jliermann Dec 2, 2025
65bfdac
refactor(theme): simplify icon handling to support only emojis for now
jliermann Dec 2, 2025
5320efc
test(theme): adapt to simplified component
jliermann Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,7 @@ export type PropSidebarItemCategory = Expand<
export type PropSidebarItemLink = SidebarItemLink & {

@slorber slorber Dec 5, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, we can customize the icon of docs/links, but not categories?

docId?: string;
unlisted?: boolean;
icon?: string;

@slorber slorber Dec 5, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This type describes above all the props that Docusaurus passes to the components, after transforming sidebar items to component props.

If you add it here just to enable a new component prop, this is quite odd because we still can't add an icon attribute to the actual sidebar item (how these cards are usually created), and can only pass it through JSX usage (less common).

We actually want to allow users to provide custom icons through sidebar files, and need to design that feature properly: #7844

};

export type PropSidebarItemHtml = SidebarItemHtml;
Expand Down
8 changes: 7 additions & 1 deletion packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,14 @@ function CardCategory({item}: {item: PropSidebarItemCategory}): ReactNode {
}

function CardLink({item}: {item: PropSidebarItemLink}): ReactNode {
const icon = isInternalUrl(item.href) ? '📄️' : '🔗';
const defaultIcon = isInternalUrl(item.href) ? '📄' : '🔗';

const customIcon =
typeof item.icon === 'string' && item.icon.length <= 2 ? item.icon : null;

@slorber slorber Dec 5, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why item.icon.length <= 2 ?

Is this an unreliable heuristic to check if the icon is an emoji?


const icon = customIcon || defaultIcon;
const doc = useDocById(item.docId ?? undefined);

return (
<CardLayout
className={item.className}
Expand Down
74 changes: 74 additions & 0 deletions website/_dogfooding/_docs tests/doc-cards-items.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import png from '@site/static/img/docusaurus.png';
import svgImg from '@site/static/img/docusaurus.svg';
import jpg from '@site/static/img/endi.jpg';

const items = [
{
label: 'Custom Icon',
description: 'Custom Icon',
href: '/docs/installation',
icon: '📖',
type: 'link',
},
{
label: 'Custom Icon',
description: 'Custom Icon',
href: '/docs/configuration',
icon: '🖥',
type: 'link',
},
{
label: 'Custom Icon (external link)',
description: 'Custom Icon (external link)',
href: 'https://react.dev/',
icon: '🛠',
type: 'link',
},
{
label: 'Default Icon (internal link)',
description: 'Default Icon (internal link)',
href: '/docs/installation',
type: 'link',
},
{
label: 'Default Icon (internal link)',
description: 'Default Icon (internal link)',
href: '/docs/configuration',
type: 'link',
},
{
label: 'Default Icon (external link)',
description: 'Default Icon (external link)',
href: 'https://react.dev/',
type: 'link',
},
{
label: 'Custom Image',
description: 'It does not break with PNG',
href: 'https://react.dev/',
icon: png,
type: 'link',
},
{
label: 'Custom Image',
description: 'It does not break with JPG',
href: '/docs/installation',
icon: jpg,
type: 'link',
},
{
label: 'Custom Image',
description: 'It does not break with SVG',
href: 'https://react.dev/',
icon: svgImg,
type: 'link',
},
];

export default items;
8 changes: 8 additions & 0 deletions website/_dogfooding/_docs tests/doc-cards.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# DocCards Test

import DocCard from '@theme/DocCard';
import DocCardList from '@theme/DocCardList';

import items from './doc-cards-items.js';

<DocCardList items={items} />

@slorber slorber Dec 5, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this works for you, but is not really the most idiomatic usage of sidebar items

Loading