> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# links

> Add templated URL links to dimension drill menus, enabling cross-linking to external tools and dashboards from query results.

Fields referenced in links are implicitly added to the query, but not shown in the result data unless explicitly included.

**Note**: Avoid referencing a dimension with more than one value for a given value of the dimension on which the link is defined, as it can impact aggregations and seemingly create duplicate rows.

## Syntax

```yaml theme={null}
<dimension_name>:
  links:
    - url: <url_template>
      label: <link_label>
      icon_url: <optional_icon_url>
```

## Properties

<ParamField path="dimension_name" type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties" defaultOpen="true">
    <ParamField path="links" type="object[]">
      An array of link objects, each containing `url`, `label`, and optionally `icon_url`.

      <Expandable title="links properties" defaultOpen="true">
        <ParamField path="url" type="string">
          The URL template, with field references using `${}` syntax.
        </ParamField>

        <ParamField path="label" type="string">
          The display text for the link.
        </ParamField>

        <ParamField path="icon_url" type="string">
          Optional URL to an image, which will display as an icon with the link.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Search engine links" theme={null}
country:
  links:
    - url: https://www.google.com/search?q=${users.country}
      label: Google
      icon_url: https://cdn4.iconfinder.com/data/icons/new-google-logo-2015/400/new-google-favicon-1024.png
    - url: https://www.bing.com/search?q=${users.country}
      label: Bing
```

<Tip>
  To inject the corresponding field into the filter URL structure, navigate to a filtered dashboard in your browser and then swap in the parameterized (dynamic) URL.
</Tip>

```yaml title="Dashboard crosslink with string filter" theme={null}
id:
  sql: '"ID"'
  format: ID
  links:
    - url: https://sandbox.omniapp.co/dashboards/KWsNP1WK?f--omni_dbt_ecomm__order_items.user_id={"values":["${omni_dbt_ecomm__users.id}"]}
      label: User Lookup Dashboard
      icon_url: https://avatars.githubusercontent.com/u/100505341?s=200&v=4
```

```yaml title="Dashboard crosslink with encoded URL" theme={null}
# For all types of filters, use the encoded URL
id:
  links:
    - url: https://sandbox.omniapp.co/dashboards/YX-irW2S/user+lookup?f--ecomm__users.id=%7B"values"%3A%5B"${ecomm__users.id}"%5D%7D
      label: User Lookup Dashboard
      icon_url: https://avatars.githubusercontent.com/u/100505341?s=200&v=4
```