UIKit SVG Component

The Complete Guide to the UIKit SVG Component

Scalable Vector Graphics (SVG) are the gold standard for iconography, logos, and simple illustrations on the web. They scale infinitely without pixelating, have tiny file sizes, and support alpha transparency. However, to truly unlock the power of SVGs—specifically the ability to style them with CSS and animate them—they must be rendered inline in the HTML DOM. This is the exact problem the UIKit SVG component solves effortlessly.

The Problem with Standard SVG Images

Traditionally, developers include an SVG file on a web page using an image tag, like this:

While this works perfectly for displaying the graphic, it creates a massive limitation. Because the SVG is trapped inside an <img> tag, your CSS stylesheet cannot reach inside the file to manipulate it.

• You cannot change the SVG's color on hover.
• You cannot alter stroke widths for dark mode.
• You cannot animate individual paths within the graphic.

The historical solution was to open the logo.svg file in a text editor, copy the massive block of XML code, and paste it directly into your HTML document (called "Inline SVG"). This solves the styling problem but creates horribly messy, unreadable HTML templates that are a nightmare to maintain.

The UIKit SVG Solution

The UIKit SVG component gives you the best of both worlds. You write clean, simple <img> tags in your HTML, and UIKit's JavaScript engine dynamically fetches the SVG file and injects its XML markup directly into the DOM right where the image tag was.

To use it, you simply add the uk-svg attribute to any image tag pointing to an SVG file:

When the page loads, UIKit replaces the <img> tag with an actual <svg> element containing all the paths and polygons from the original file. Crucially, any CSS classes or attributes (like width and height) that you had on the original <img> tag are automatically transferred to the newly injected <svg> element.

Styling Injected SVGs with CSS

Once UIKit has injected the SVG inline, you gain complete CSS control over its appearance. The most common use case is changing the color of an icon based on its parent container or hover state.

By default, many SVG elements use the fill or stroke attributes to define their colors. To allow CSS to control these colors, the SVG paths should ideally use fill="currentColor". When an SVG is set to currentColor, it automatically inherits the text color of whatever CSS class is applied to it.

Because UIKit transfers classes, you can simply use standard UIKit typography colors to change the icon color:

The Stroke Animation Feature

One of the most impressive features of the UIKit SVG component is its built-in support for "line drawing" animations. This is a popular visual effect where an icon appears to be drawn onto the screen in real-time.

To achieve this, UIKit automatically calculates the exact length of every <path> inside the SVG using JavaScript. It then manipulates the stroke-dasharray and stroke-dashoffset CSS properties to hide the stroke and slowly reveal it via a CSS transition.

You can trigger this effect simply by adding the stroke-animation: true parameter to the component:

Important Requirements for Stroke Animation:For this animation to work, the SVG file must meet specific criteria:

1. The SVG must be drawn using Strokes, not Fills. If a designer creates an icon using solid shapes (fills), there are no lines to "draw," and the animation will fail.
2. The SVG paths must not have any pre-defined stroke-dasharray attributes.
3. The stroke color must be visible.

Handling Cross-Origin Resource Sharing (CORS)

Because the UIKit SVG component uses JavaScript (specifically the fetch() API or XMLHttpRequest) to download the contents of the SVG file before injecting it, you must be aware of CORS restrictions.

If you attempt to load an SVG from a different domain (e.g., your website is on mysite.com but the src points to cdn.othersite.com/icon.svg), the browser will block the request for security reasons unless the remote CDN explicitly sends CORS headers allowing the request.

Therefore, it is highly recommended to host your SVG files locally on your own domain to avoid CORS failures that will result in broken, missing icons.

Caching and Performance

A common concern developers have with injecting SVGs via JavaScript is performance. If a page has 50 identical "check-mark.svg" icons on a to-do list, will UIKit send 50 separate HTTP requests to the server?

The answer is no. The UIKit SVG component is highly optimized. When it encounters the uk-svg attribute, it first checks an internal cache. If the SVG file has already been downloaded during the current page session, UIKit instantly pulls the XML markup from memory rather than executing another network request. This makes the component incredibly fast, even when rendering hundreds of icons simultaneously.

Accessibility (A11y)

When injecting SVGs, you must ensure they remain accessible to screen readers. If the SVG is purely decorative (like a background pattern or a minor UI flair), it should be hidden from screen readers.

Because UIKit retains the attributes of the original <img> tag, the best practice is to always provide a descriptive alt text if the icon is meaningful (e.g., a magnifying glass used as a search button). However, because the injected tag becomes an <svg>, the alt attribute isn't strictly standard.

A more robust approach for critical UI icons is to include aria-hidden="true" on the image tag, and place visually hidden screen-reader text next to it:

This ensures that visual users see the beautifully injected SVG, while visually impaired users receive clear, unambiguous text instructions.