Icon API RTL Behavior: Handling What You Can’t Verify

Updated 15 November 2026 · Standard formula, shown below

This guide explains how an icon API can handle right-to-left (RTL) behavior when the API itself cannot verify the directionality of the surrounding text or layout. You’ll learn a practical approach using CSS logical properties, explicit direction flags, and defensive fallbacks—so icons render correctly in both LTR and RTL contexts without relying on the API to guess.

What You’ll Need

An icon API or icon font you control (or can wrap).
Basic knowledge of CSS and HTML.
Access to the icon rendering code (e.g., a CSS file or a JavaScript component).

Step-by-Step

Understand the limitation. The API cannot verify RTL because it doesn’t know the dir attribute of the parent element or the computed text direction. It only sees the icon markup. So you must design the API to be direction-agnostic by default.
Use CSS logical properties for icon transforms and positioning. Replace physical properties like left, right, margin-left, and padding-right with logical equivalents: inset-inline-start, margin-inline-end, etc. This way, the icon automatically flips when the parent has dir="rtl".
For icons that need to flip (e.g., arrows, chevrons), apply a CSS transform based on the direction. Add a rule like [dir="rtl"] .icon-arrow { transform: scaleX(-1); }. But since the API can’t know the parent’s dir, you should instead provide a class or attribute that the consumer can add when they know the context is RTL.
Provide an explicit dir prop or attribute in the API. If you’re building a component, accept a dir prop (values: ltr, rtl, or auto). When auto, the component can read the computed direction of its parent using JavaScript (e.g., getComputedStyle(element).direction)—but only if you’re in a DOM environment. For static CSS, you can’t.
If you can’t read the parent’s direction, default to LTR and document the limitation. The API should render icons without any RTL-specific transforms by default. Then provide a utility class like .icon--rtl that consumers can apply to flip the icon manually.
For icon fonts, use Unicode characters that are direction-neutral. Avoid using characters that have inherent directional properties (like some arrows). Instead, use private use area characters or SVG that you control, and apply transforms as needed.
Test with both directions. Even though you can’t verify automatically, you can test your API in a controlled environment with dir="rtl" on a parent to ensure your logical properties and flip classes work.
Document the behavior clearly. In your API docs, state that RTL support is provided via CSS logical properties and an optional dir attribute, but that the API itself does not auto-detect direction. Provide examples for both LTR and RTL.

Common Mistakes

Using physical properties in icon styles. If you use left: 2px for a badge, it won’t flip in RTL. Always use logical properties.
Assuming the icon will flip automatically. Without explicit CSS or a dir attribute, the icon will stay the same. Don’t rely on the browser to flip it.
Applying scaleX(-1) to all icons. Only directional icons (arrows, chevrons, carets) should flip. Mirrored text or logos would be wrong.
Ignoring the parent’s direction. If the parent has dir="rtl", your logical properties will work, but your transforms won’t unless you target them.

Tips

Use CSS variables for direction. Set a CSS variable like --icon-flip: 1 in LTR and --icon-flip: -1 in RTL. Then apply transform: scaleX(var(--icon-flip)) to directional icons.
Provide a global CSS override. Let consumers add a simple rule like [dir="rtl"] .icon { /* your flip rules */ } to handle all icons at once.
For JavaScript components, use useLayoutEffect to check the parent’s direction. This gives you the ability to set a state that flips the icon, but only if the parent’s direction changes—you’ll need to listen for changes.
Keep icons symmetrical when possible. If an icon can be designed to look the same in both directions, you avoid the problem entirely.

Troubleshooting

Icon doesn’t flip in RTL. Check if the parent has dir="rtl" and if your CSS uses logical properties. If you’re using a transform, ensure the selector matches the icon’s class and that the transform isn’t overridden.
Icon flips in LTR unexpectedly. This usually happens when you applied a global flip rule without checking the direction. Make sure your flip rule is scoped to [dir="rtl"] only.
Icon position is wrong in RTL (e.g., badge on the wrong side). You used a physical property like right: 0. Replace it with inset-inline-end: 0.
JavaScript component can’t detect direction. Ensure you’re reading the correct element (the parent, not the icon itself). Use element.closest('[dir]') to find the nearest ancestor with a dir attribute.

Frequently Asked Questions

Can the API automatically detect RTL?

No, not reliably. The API doesn’t know the context of the surrounding text. It can only read the direction if you pass it explicitly or if it’s in a DOM environment and you query the parent’s computed style.

What is a logical property?

Logical properties are CSS properties that map to physical properties based on the writing mode. For example, margin-inline-start is the left margin in LTR and the right margin in RTL. They help your layout adapt automatically.

Should I flip all icons in RTL?

No, only icons that have a directional meaning, like arrows or chevrons. Icons that are symmetrical or have no direction (like a home icon) should not be flipped.

How do I flip an icon using CSS?

Use transform: scaleX(-1) on the icon element. To make it conditional, wrap it in a rule like [dir="rtl"] .icon-arrow { transform: scaleX(-1); }.

What if I’m using an icon font and the glyph is already mirrored?

If the glyph is inherently directional, you’ll need to use a different glyph or apply a transform. Some icon fonts provide separate RTL variants—use those if available.

Can I rely on the `dir` attribute on the icon element itself?

Yes, if you set dir="rtl" on the icon element, it will affect the rendering of that element, but it won’t automatically flip the icon’s visual content. You still need CSS to apply the flip.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.