## NavLink A Navlink component. Category: Navigation ### Basic usage Use `NavLink`'s `n_clicks` property in callbacks, or you can set `href` to make it a link. ```python import dash_mantine_components as dmc from dash import html from dash_iconify import DashIconify def get_icon(icon): return DashIconify(icon=icon, height=16) component = html.Div( [ dmc.NavLink( label="With icon", leftSection=get_icon(icon="bi:house-door-fill"), ), dmc.NavLink( label="With right section", leftSection=get_icon(icon="tabler:gauge"), rightSection=get_icon(icon="tabler-chevron-right"), ), dmc.NavLink( label="Disabled", leftSection=get_icon(icon="tabler:circle-off"), disabled=True, ), dmc.NavLink( label="With description", description="Additional information", leftSection=dmc.Badge( "3", size="xs", variant="filled", color="red", w=16, h=16, p=0 ), ), dmc.NavLink( label="Active subtle", leftSection=get_icon(icon="tabler:activity"), rightSection=get_icon(icon="tabler-chevron-right"), variant="subtle", active=True, ), dmc.NavLink( label="Active light", leftSection=get_icon(icon="tabler:activity"), rightSection=get_icon(icon="tabler-chevron-right"), active=True, ), dmc.NavLink( label="Active filled", leftSection=get_icon(icon="tabler:activity"), rightSection=get_icon(icon="tabler-chevron-right"), variant="filled", active=True, ), ], style={"width": 240}, ) ``` ### Active styles Set `active` prop to add active styles to `NavLink`. You can customize active styles with `color` and `variant` properties. ```python import dash_mantine_components as dmc from dash_iconify import DashIconify dmc.NavLink( label="With right section", leftSection=DashIconify(icon="tabler:gauge"), active=True, variant="filled", color="orange", id="navlink-interactive", rightSection=DashIconify(icon="tabler-chevron-right"), ), ``` ### Setting Active prop based on URL The `active` prop in `NavLink` controls whether a link is highlighted as active. It can be set manually (`True`/`False`) or automatically based on the current URL. `active` can be set dynamically without using dash callbacks: - `"exact"` → Active when the current pathname matches `href` path - `"exact-with-search`→ Active when the current pathname matches `href` path and query strings - `"partial"` → Active when the current pathname starts with `href` (includes subpages) - `"children"` → Parent link active when any child link is active Example: - User on `/page-1/subject-1` → The second and third links are active (since `"partial"` includes subpages). - User on `/page-1` → Only the second link is active. ```python html.Div([ dmc.NavLink(label="Home", href="/home", active="exact"), dmc.NavLink(label="Page 1", href="/page-1", active="partial"), dmc.NavLink(label="Subject 1", href="/page-1/subject-1", active="exact"), ]) ``` See a complete example in Multi-Page App Example with Active Links section. ### Setting active prop in a callback Use a callback to set `active` prop if you are using dash-mantine-components<1.0.0 This example demonstrates how to use a callback to set the `active` prop of the `NavLink` when the user navigates to a different page. It uses the "Dash Pages" feature but can be adapted to any other page navigation system. ```python # Create Navlinks (using dash.page_registry) [ dmc.NavLink( label=f"{page['name']}", href=page["relative_path"], id={"type": "navlink", "index": page["relative_path"]}, ) for page in page_registry.values() ] # ... # Callback (using the dcc.location provided by Dash Pages) @app.callback(Output({"type": "navlink", "index": ALL}, "active"), Input("_pages_location", "pathname")) def update_navlinks(pathname): return [control["id"]["index"] == pathname for control in callback_context.outputs_list] ``` ### Nested NavLinks To create nested links put dmc.NavLink as children of another dmc.NavLink. ```python import dash_mantine_components as dmc from dash import html from dash_iconify import DashIconify def get_icon(icon): return DashIconify(icon=icon, height=16) component = html.Div( style={"width": 240}, children=[ dmc.NavLink( label="First parent link", leftSection=get_icon(icon="tabler:gauge"), childrenOffset=28, children=[ dmc.NavLink(label="First child link"), dmc.NavLink(label="Second child link"), dmc.NavLink( label="Nested parent link", childrenOffset=28, children=[ dmc.NavLink(label="First child link"), dmc.NavLink(label="Second child link"), dmc.NavLink(label="Third child link"), ], ), ], ), dmc.NavLink( label="Second parent link", leftSection=get_icon(icon="tabler:fingerprint"), childrenOffset=28, opened=True, children=[ dmc.NavLink(label="First child link"), dmc.NavLink(label="Second child link"), dmc.NavLink(label="Third child link"), ], ), ], ) ``` ### Multi-Page App Example with Active Links This example uses [Dash Pages](https://dash.plotly.com/urls) to create a simple multi-page app. For simplicity, all pages are defined in a single file instead of separate folders. It demonstrates `active="exact-with-search"` with query strings and shows how `active="children"` keeps a parent link active when a child route is selected. ```python import dash import dash_mantine_components as dmc app = dash.Dash(use_pages=True, pages_folder="") def reports_layout(type=None, **kwargs): return dmc.Box(f"{type} Report ") dash.register_page("home", path="/", layout=dmc.Box("Home")) dash.register_page("reports", path="/reports", layout=reports_layout) dash.register_page("settings", path="/settings", layout=dmc.Box("Settings")) nav = dmc.Box([ dmc.NavLink(label="Home", href="/", active="exact"), dmc.NavLink( label="Reports", active="children", childrenOffset=28, children=[ dmc.NavLink( label="Sales", href="/reports?type=Sales", active="exact-with-search", ), dmc.NavLink( label="Inventory", href="/reports?type=Inventory", active="exact-with-search", ), ], ), dmc.NavLink(label="Settings", href="/settings", active="exact"), ]) app.layout = dmc.MantineProvider( dmc.AppShell( [ dmc.AppShellNavbar(nav), dmc.AppShellMain(dash.page_container), ], padding="xl", navbar={"width": 300}, ) ) if __name__ == "__main__": app.run(debug=True) ``` ### Styles API This component supports Styles API. With Styles API, you can customize styles of any inner element. See the Styling and Theming sections of these docs for more information. | Name | Static selector | Description | |:------------|:-----------------------------|:---------------------------------------------| | root | .mantine-NavLink-root | Root element | | body | .mantine-NavLink-body | Contains label and description | | section | .mantine-NavLink-section | Left and right sections | | label | .mantine-NavLink-label | NavLink label | | description | .mantine-NavLink-description | Dimmed description displayed below the label | | children | .mantine-NavLink-children | Wrapper around nested links | | chevron | .mantine-NavLink-chevron | Default chevron icon | | collapse | .mantine-NavLink-collapse | Nested links Collapse container | ### Keyword Arguments #### NavLink - children (a list of or a singular dash component, string or number; optional): Child `NavLink` components. - id (string; optional): Unique ID to identify this component in Dash callbacks. - active (boolean; default False): Controls whether the link is styled as active (default: `False`). - aria-* (string; optional): Wild card aria attributes. - attributes (boolean | number | string | dict | list; optional): Passes attributes to inner elements of a component. See Styles API docs. - autoContrast (boolean; optional): Determines whether button text color with filled variant should depend on `background-color`. If luminosity of the `color` prop is less than `theme.luminosityThreshold`, then `theme.white` will be used for text color, otherwise `theme.black`. Overrides `theme.autoContrast`. - childrenOffset (number; optional): Key of `theme.spacing` or any valid CSS value to set collapsed links `padding-left`, `'lg'` by default. - className (string; optional): Class added to the root element, if applicable. - classNames (dict; optional): Adds custom CSS class names to inner elements of a component. See Styles API docs. - color (optional): Key of `theme.colors` of any valid CSS color to control active styles, `theme.primaryColor` by default. - darkHidden (boolean; optional): Determines whether component should be hidden in dark color scheme with `display: none`. - data-* (string; optional): Wild card data attributes. - description (a list of or a singular dash component, string or number; optional): Link description, displayed below the label. - disableRightSectionRotation (boolean; optional): If set, right section will not be rotated when collapse is opened, `False` by default. - disabled (boolean; optional): If set, disabled styles will be added to the root element, `False` by default. - hiddenFrom (string; optional): Breakpoint above which the component is hidden with `display: none`. - href (string; optional): href. - label (a list of or a singular dash component, string or number; optional): Main link label. - leftSection (a list of or a singular dash component, string or number; optional): Section displayed on the left side of the label. - lightHidden (boolean; optional): Determines whether component should be hidden in light color scheme with `display: none`. - loading_state (dict; optional): Object that holds the loading state object coming from dash-renderer. For use with dash<3. `loading_state` is a dict with keys: - mod (string | dict | list of string | dicts; optional): Element modifiers transformed into `data-` attributes. For example: "xl" or {"data-size": "xl"}. Can also be a list of strings or dicts for multiple modifiers. Falsy values are removed. - n_clicks (number; default 0): An integer that represents the number of times that this element has been clicked on. - noWrap (boolean; optional): If set, label and description will not wrap to the next line, `False` by default. - opened (boolean; default False): Controlled nested items collapse state. - persisted_props (list of strings; optional): Properties whose user interactions will persist after refreshing the component or the page. Since only `value` is allowed this prop can normally be ignored. - persistence (string | number | boolean; optional): Used to allow user interactions in this component to be persisted when the component - or the page - is refreshed. If `persisted` is truthy and hasn't changed from its previous value, a `value` that the user has changed while using the app will keep that change, as long as the new `value` also matches what was given originally. Used in conjunction with `persistence_type`. Note: The component must have an `id` for persistence to work. - persistence_type (a value equal to: 'local', 'session', 'memory'; optional): Where persisted user changes will be stored: memory: only kept in memory, reset on page refresh. local: window.localStorage, data is kept after the browser quit. session: window.sessionStorage, data is cleared once the browser quit. - refresh (boolean; optional): Whether to refresh the page. - rightSection (a list of or a singular dash component, string or number; optional): Section displayed on the right side of the label. - styles (boolean | number | string | dict | list; optional): Adds inline styles directly to inner elements of a component. See Styles API docs. - tabIndex (number; optional): tab-index. - target (a value equal to: '_blank', '_self'; optional): Target. - variant (string; optional): variant. - visibleFrom (string; optional): Breakpoint below which the component is hidden with `display: none`.