Fix popup arrow overlapping text

[TCWORLD]

This is a rehash of #1437 but with additional changes to avoid the visual artefacts that meant that PR could not be merged.

I'm opening this again as the original change was manually applied in the home-assistant fork and keeps getting lost whenever the version is upgraded, so it would be good to get it pushed back upstream.

---

The backstory for why is the same as in the linked PR, because the arrow on the popup element is a diamond not a triangle, it interferes with the content of the popup:

The original fix was to add a clipping mask to the diamond to turn it into a triangle. This however caused problems when there was a border on the host element - the cropping was to the outside edge of the host border, leaving the border visible.

To resolve this, the arrow now has some additional styling applied to grow and translate it to overlap and thus hide the border of the host. This calculation is done by specifying --popup-border-width for the popup element (given as width of border). The arrow then takes care of scaling itself up to overlap to the inner edge of the border.

To visualise it, here is the arrow showing on the popover element that caused problems last time, filled in red to see how it is cropped:

Scaling up the size of the border to demonstrate the accuracy of the maths, we get:

And just normally:

[vercel]

@TCWORLD is attempting to deploy a commit to the Font Awesome Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
webawesome	Ready	Preview	Feb 18, 2026 3:17pm

[claviska]

Thanks for the PR.

• Can we add a changelog entry about this and highlight the new public custom property --arrow-border-size (it looks like the others that were added are computed/internal)
• Can we fix the popup example? When arrow is enabled, it should show up here but it doesn't.
  

We should probably also add an example demonstrating how to use this to the popup docs, maybe with the arrow border showing a different color. I'm happy to add the example and the changelog if you don't mind making sure the examples are working as intended.

[TCWORLD]

I'll have a look at why the popup arrow is not working - it was on my dev setup, but I may have changed something.

The --arrow-border-size (perhaps it should be width for consistency) was added so that if an element tries to add a border to its popup, the size can be calculated to overlay the border, happy to add an explanation of that to the docs also.

I'll do some further tinkering tomorrow.

[TCWORLD]

@claviska Fixed the missing arrows on the popup - the joys of CSS treating 0 and 0px as different things for size calculations!

I've also tried to make a slight tweak to the clipping mask to minimise/remove artefacts caused by sub-pixel rounding, but I think there is more going on - probably related to the translation of the arrow when selecting start/end. I'll investigate.

[TCWORLD]

Ok, I think I've got it working properly now. I missed that the popup.ts file modifies the position of the arrow which was meant the translation I made in the CSS file was getting lost hence weird visual artefacts. I've corrected this by making the translation part of the positioning in the popup.ts file.

[TCWORLD]

All looks functional now from what I can tell.

I've renamed the new variable to --popup-border-width because it's actually not at all to do with the border on the arrow itself, but rather any border applied to the main popup element content. This is because the width of that border needs to be known to position the arrow such that it is covered up and makes the arrow appear to merge with the contents.

I've added the changelog entries as requested. I've also added an explanation of the new variable to the popup.md file.

Also added an example of how to stylise the border of the popup, including setting the --popup-border-width parameter and targeting the arrow itself.