## 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.  

*New in dash-mantine-components > = 1.0.0*  

Now, `active` can be set dynamically:  
- `"exact"` → Active when the current pathname matches `href`.  
- `"partial"` → Active when the current pathname starts with `href` (includes subpages).  

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
Here's a minimal multi-page app example using Pages. It demonstrates how `active="exact"` and `active="partial"`
automatically apply active styles based on the current URL

```python
import dash
import dash_mantine_components as dmc
from dash import Dash, html

app = Dash(use_pages=True, pages_folder="")

dash.register_page("home", path="/", layout=html.Div("I'm home"))
dash.register_page("page1", path="/page-1", layout=html.Div("Info about page 1 subjects"))
dash.register_page("page1s1", path="/page-1/sub-1", layout=html.Div("page 1 subject 1"))
dash.register_page("page1s2", path="/page-1/sub-2", layout=html.Div("page 1 subject 2"))

component = dmc.Box([
    dmc.NavLink(label="home", href="/", active='exact'),
    dmc.NavLink(
            label="Page 1",
            childrenOffset=28,
            href="/page-1",
            active='partial',
            children=[
                dmc.NavLink(label="Subject 1", href="/page-1/sub-1", active="exact"),
                dmc.NavLink(label="Subject 2", href="/page-1/sub-2", active="exact"),
            ],
    ),
    dmc.Divider(mb="lg"),
    dash.page_container
])


app.layout = dmc.MantineProvider([component])

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`.