UIKit Subnav Component

The Complete Guide to the UIKit Subnav Component

While every website has a primary header navigation bar (usually built with the UIKit Navbar component), complex interfaces frequently require secondary, localized navigation. Whether you are building a filter menu for a blog, a category list for an e-commerce sidebar, or tabbed settings panels, the UIKit Subnav component is the ideal semantic structure.

The Subnav component strips away the heavy styling of a primary navbar, providing a clean, inline list of links that can be easily modified with visual separators, "pill" background styles, and dropdown menus.

Basic Structure and Semantics

At its core, a Subnav is simply an unordered HTML list. To initialize the component styling, you apply the .uk-subnav class to the <ul> tag. You must then wrap the text inside each <li> within an anchor <a> tag or a <span> tag.

Key Structural Rules:

• Active State: Add the .uk-active class to the <li> to visually indicate the current page or active filter. UIKit will automatically style this item differently (e.g., darker text or a filled background).
• Disabled State: If an item shouldn't be clickable, replace the <a href> tag with a <span> tag. UIKit will automatically mute the color and remove the hover cursor.

Visual Modifiers: Dividers and Pills

A raw Subnav is just a horizontal row of text links. To give it structure and visual appeal, UIKit provides two primary modifier classes.

1. The Divider Modifier (.uk-subnav-divider):
By adding this class to the <ul>, UIKit automatically injects vertical lines (using border-right CSS on pseudo-elements) between the list items. This is a classic UI pattern often used in footers (e.g., "Privacy Policy | Terms of Service | Contact"). It ensures the links don't visually bleed into one another.

2. The Pill Modifier (.uk-subnav-pill):
This is arguably the most popular use case for Subnav. Adding this class removes the default text styling and instead applies a background color to the active item, with large rounded corners (border-radius) that resemble a pill. When the user hovers over inactive items, they also receive a subtle pill-shaped background hover state. This style is ubiquitous in modern web design for portfolio filters (e.g., "All / Web Design / Branding / Photography").

Alignment and Flexbox Integration

Because the Subnav component is built using CSS Flexbox under the hood, it pairs flawlessly with UIKit's Flex utility classes. This allows you to position the menu exactly where you need it without writing custom CSS floats.

• Center Alignment: Add .uk-flex-center to the <ul> to center the entire navigation block horizontally.
• Right Alignment: Add .uk-flex-right to align the menu to the far right of its container.
• Space Between: Add .uk-flex-between if you have a wide container and want the list items spread evenly across the entire width.

Handling Wrapping on Mobile Devices

A common issue with horizontal navigation menus is that they break when viewed on narrow mobile phone screens. If you have 6 items in your Subnav, they will likely overflow the screen edge.

Because Subnav uses Flexbox, the items will naturally wrap to a second line if they run out of space. However, when they wrap, the vertical spacing between the top row and the bottom row is often non-existent, causing the text to smash together.

The solution is the UIKit Margin component. By adding the uk-margin attribute directly to the <ul class="uk-subnav">, the UIKit JavaScript engine will detect when the flex items wrap to a new line and automatically apply a top margin to the wrapping elements, ensuring perfect spacing regardless of screen size.

Integrating Dropdown Menus

Sometimes a single list of links isn't enough. If you have a "Sort By" filter in your Subnav, you might want clicking it to reveal a list of options (Date, Price, Popularity).

The Subnav component integrates perfectly with the UIKit Dropdown component. You simply attach a dropdown container immediately after the <a> tag within the list item.

In this setup, the uk-dropdown component handles the hovering/clicking logic, while the internal .uk-nav component handles the vertical list styling inside the popup. It creates a seamless, professional interaction.

Subnav vs Navbar vs Nav: When to use what?

UIKit offers three distinct navigation components, which can sometimes confuse developers. Here is the definitive rule of thumb for when to use Subnav:

• Navbar (uk-navbar): Used exclusively for the main, top-level site header. It supports complex layouts like left/right alignment, massive dropdown mega-menus, and brand logos.
• Nav (uk-nav): Used exclusively for vertical lists of links. If you are building a sidebar menu or the internal links inside a dropdown popup, use Nav.
• Subnav (uk-subnav): Used for horizontal, secondary lists. If it sits below the main header, is meant to filter content, and flows horizontally left-to-right, Subnav is the correct semantic choice.