Icons render as svg symbols (fix icon clipping)

[BrettJephson]

This change fixes the rendering of Font Awesome icons, which can become clipped.

Fixes RND-10291

Because we have been loading in the svg as an image file and applying a mask for colour we could not simply use overflow: visible to prevent clipping of images that overflow the svg’s viewbox. It is already a rasterized image so we only show the bit in the image canvas.

The solution here is to render svg as an actual svg symbol in the document creating a spritesheet so we are using symbol definitions and use and some id. This way we can reuse the svg symbol if it appears in multiple places in a page.

This better aligns with Font Awesome’s recommended usage on the web and fixes the clipping and slightly improves rendering while keeping the size of icons the same.

Demo

Before:

After:

[changeset-bot]

🦋 Changeset detected

Latest commit: 6cd9f2a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@gitbook/icons	Minor
gitbook	Patch
@gitbook/react-contentkit	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Summary of the deployments:

Version	URL	Status
Vercel	https://gitbook-v2-996obduv6-gitbook.vercel.app	✅
Cloudflare	https://97a44496-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-996obduv6-gitbook.vercel.app/url/gitbook.com/docs	https://97a44496-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-996obduv6-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://97a44496-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.gitbook.io/test-gitbook-open

[linear]

RND-10291 FA icons are getting clipped

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
customers-v2-cloudflare (Inspect)	👍 Changes approved	86 changed	Apr 30, 2026, 7:47 PM
customers-v2-vercel (Inspect)	👍 Changes approved	86 changed	Apr 30, 2026, 7:46 PM
v2-cloudflare (Inspect)	👍 Changes approved	397 changed	Apr 30, 2026, 7:53 PM
v2-vercel (Inspect)	👍 Changes approved	399 changed	Apr 30, 2026, 7:51 PM

[conico974]

Maybe I misunderstood something, but are we loading the icons with fetch on the client side ?
It means that we have to wait for hydration to be done and for JS to be fully loaded before even attempting to load the icons.
I can also see the behavior on initial load here https://gitbook-v2-fh22isgp4-gitbook.vercel.app/url/gitbook.com/docs, it takes a noticeable amount of times before icon start showing