NavLink

The NavLink component defines a navigation target (app navigation menu item) within the app; it is associated with a particular in-app navigation target (or an external link).

Using NavLink

NavLink Appearance

You can use the label and icon properties of a NavLink to set its text and icon to display. If you want a custom appearance, you can nest define custom visuals for the NavLink by nesting:

<App layout="horizontal">
  <AppHeader>
    <H1>MyApp</H1>
  </AppHeader>
  <NavPanel>
    <NavLink to="/">
       <Stack width="16px" height="16px" backgroundColor="purple" />
       Home
    </NavLink>
    <NavLink to="/about">
       <Stack width="16px" height="16px" backgroundColor="green" />
       About
    </NavLink>
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
    <Page url="/about">About</Page>
  </Pages>
</App>

Actions

By default, activating (clicking) a link navigates to the target URL. However, you can create a link that executes an explicit action responding to the click event instead of the default navigation:

<App layout="horizontal">
  <AppHeader>
    <H1>MyApp</H1>
  </AppHeader>
  <NavPanel>
    <NavLink to="/" label="Home" />
    <NavLink label="Danger!" onClick="toast('Be careful with this action!')" />
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
  </Pages>
</App>

Properties

active (default: false)

This property indicates if the particular navigation is an active link. An active link has a particular visual appearance, provided its displayActive property is set to true.

displayActive (default: true)

This Boolean property indicates if the active state of a link should have a visual indication. Setting it to false removes the visual indication of an active link.

<App layout="horizontal">
  <NavPanel>
    <NavLink to="/" label="Home" displayActive="false" />
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
  </Pages>
</App>

enabled (default: true)

This boolean property value indicates whether the component responds to user events (true) or not (false).

In the following app, the "Hotels" link is disabled:

<App layout="horizontal">
  <AppHeader>
    <H1>MyTravel App</H1>
  </AppHeader>
  <NavPanel>
    <NavLink label="Home" to="/" />
    <NavLink label="Flights" to="/flights" />
    <NavLink label="Hotels" to="/hotels" enabled="false" />
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
    <Page url="/flights">Flights Page</Page>
    <Page url="/hotels">Hotels Page</Page>
  </Pages>
</App>

icon

This property allows you to add an icon (specify the icon's name) to the navigation link.

<App layout="horizontal">
  <AppHeader>
    <H1>MyApp</H1>
  </AppHeader>
  <NavPanel>
    <NavLink label="Home" to="/" icon="home" />
    <NavLink label="Drives" to="/drives" icon="drive" />
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
    <Page url="/drives">Drives Page</Page>
  </Pages>
</App>

label

This property sets the label of the component.

<App layout="horizontal">
  <NavPanel>
    <NavLink to="/" label="Home" />
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
  </Pages>
</App>

target (default: "_self")

This property specifies how to open the clicked link.

Available values:

The following example opens the "About XMLUI" link in a new tab:

<App layout="horizontal">
  <AppHeader>
    <H1>MyApp</H1>
  </AppHeader>
  <NavPanel>
    <NavLink label="Home" to="/" />
    <NavLink label="About XMLUI" to="https://docs.xmlui.com/" target="_blank" />
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
    <Page url="/drives">Drives Page</Page>
  </Pages>
</App>

to

This property defines the URL of the link.

vertical (default: false)

This property sets how the active status is displayed on the NavLink component. If set to true, the indicator is displayed on the side which lends itself to a vertically aligned navigation menu.

Usually, you do not need to use this property. However, if you create a custom navigation menu component that runs vertically, you need to manually set this property for the active state to be displayed properly.

The default value for this property is false.

<App layout="horizontal">
  <NavPanel>
    <NavLink to="/" label="Home" vertical="true" />
  </NavPanel>
  <Pages>
    <Page url="/">Home</Page>
  </Pages>
</App>

Events

click

This event is triggered when the NavLink is clicked.

The following example shows a message and navigates to the "/status" link after closing the message window:

Exposed Methods

This component does not expose any methods.

Styling

The Navlink component uses these theme variables to customize its appearance:

• backgroundColor: (with these states: --hover, --hover--active, --active, --pressed, --pressed-active)
• color-indicator: (with these states: --hover, --active, --pressed)
• textColor: (with these states: --hover, --hover--active, --active, --pressed, --pressed-active)
• color-icon
• fontSize
• fontWeight: (with these states: --active, --pressed)
• paddingHorizontal
• paddingVertical
• borderRadius
• borderRadius-indicator
• thickness-indicator

The theme variables ending with indicator set the indicator's visual properties that sign the link's active state.

The following sample theme sets a few visual properties of NavLink. It changes the background color to show the hovered state and modifies the indicator's visual appearance. The theme displays the link with an extra bold font:

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "backgroundColor-NavLink--hover": "deepskyblue",
    "backgroundColor-NavLink--pressed": "steelblue",
    "backgroundColor-NavLink--active": "lightblue",
    "backgroundColor-NavLink--hover--active": "deepskyblue",
    "color-indicator-NavLink--active": "purple",
    "thickness-indicator-NavLink": "4px",
    "fontWeight-NavLink": "900"
  }
}

Theme Variables

Variable Explanations