Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

import { Property, PropertyList, ExpandableSection } from "@wix/docs-ui/content";

# Link

A navigation target the Wix user picks in the editor, such as an external URL, another page,
or an anchor. Use it for any field whose value points somewhere. At runtime it's an
object with the address and how the link should open.

## Component

In your component code, import the `Link` type from `@wix/editor-react-types`:

```ts
import type { Link } from '@wix/editor-react-types';
```

A `Link` has the following properties:

<PropertyList bordered>
  <Property
    name="href"
    type="string"
    description="The link address. On a partial link this holds only the router prefix, not a full URL."
  />
  <Property
    name="target"
    type="'_self' | '_blank'"
    description="Where the link opens. '_self' uses the same tab, '_blank' a new tab."
  />
  <Property name="rel" type="string">
    The anchor rel attribute, as space-separated values such as `'noopener noreferrer'`.
  </Property>
  <Property
    name="pageRole"
    type="string"
    description="Present only on a partial link. Names the page whose full URL the router resolves at runtime. You read it to detect a partial link. You normally do not set it."
  />
</PropertyList>

### Usage

Your code either consumes a value of type `Link` or produces one:

::::tabs
:::Consumers
In a component that receives a `Link`, apply its fields to an anchor element:

```tsx
import type { Link } from '@wix/editor-react-types';

function CallToAction({ ctaLink }: { ctaLink?: Link }) {
  return (
    <a href={ctaLink?.href} target={ctaLink?.target} rel={ctaLink?.rel}>
      Shop now
    </a>
  );
}
```

A link can be partial. When `pageRole` is set, `href` holds only the page prefix and is
not directly navigable, so check `pageRole` and resolve the full URL before navigating:

```tsx
function resolveHref(ctaLink: Link): string | undefined {
  if (ctaLink.pageRole) {
    // The full URL is owned by the Router or App that defines this pageRole. Hand the
    // href prefix and pageRole to that app to resolve at runtime. A generic consumer
    // cannot build the full URL on its own, so href here is not navigable.
    return undefined;
  }
  return ctaLink.href;
}
```
:::
:::Producers
When your code produces a `Link`, for a context or a function return, set `href`,
`target`, and `rel` for the consumer to apply:

```ts
import type { Link } from '@wix/editor-react-types';

const ctaLink: Link = {
  href: 'https://example.com',
  target: '_blank',
  rel: 'noopener',
};
```
:::
::::

## Manifest

In your manifest, declare the field with the `link` dataType:

```json
{ "dataType": "link" }
```

### Declaration

Declare a `link` field in one of these ways, depending on where the value comes from:

::::tabs
:::Data-property
Declare it as a data property when the Wix user picks the link in a panel. It takes
`dataType`, `displayName`, an optional `defaultValue`, and the options that follow:

```json
{
  "ctaLink": {
    "dataType": "link",
    "displayName": "Call to Action",
    "defaultValue": { "href": "https://example.com", "target": "_blank", "rel": "noopener" },
    "link": {
      "linkTypes": ["externalLink", "pageLink"]
    }
  }
}
```

#### Options

A `link` data property accepts the following options:

<PropertyList bordered>
  <Property
    name="linkTypes"
    type="LinkType[]"
    description="The kinds of link the Wix user may choose. Defaults to all of them."
  >
    <ExpandableSection name="LinkType values">
      <PropertyList>
        <Property name="'externalLink'">
          Another website. For example, `'https://example.com'`.
        </Property>
        <Property name="'pageLink'">
          Another page on the site. Its `href` resolves to the page's URL, such as `'/about'`.
        </Property>
        <Property name="'anchorLink'">
          An item on the current page. Its `href` resolves to the page URL plus the item's
          fragment, such as `'/about#team'`.
        </Property>
        <Property name="'emailLink'">
          An email address. For example, `'mailto:hello@example.com'`.
        </Property>
        <Property name="'phoneLink'">
          A phone number. For example, `'tel:+15551234567'`.
        </Property>
        <Property name="'dynamicPageLink'">
          A Wix app page resolved at runtime. Its `href` resolves to the app route, such as
          `'/blog/my-post'`. When only the top-level route is known, it stays a partial link,
          with `href` holding the router prefix and `pageRole` set.
        </Property>
        <Property name="'whatsAppLink'">
          A WhatsApp conversation. Its `href` resolves to a `https://api.whatsapp.com/send?phone=`
          URL.
        </Property>
        <Property name="'documentLink'">
          A document hosted by Wix, such as a PDF. Its `href` resolves to a URL to the hosted
          file.
        </Property>
        <Property name="'popupLink'">
          A lightbox on the site. Its `href` resolves to the current page URL with a `?popup=`
          query.
        </Property>
        <Property name="'addressLink'">
          An address on a map. Its `href` resolves to a Google Maps `http://maps.google.com/maps?daddr=`
          URL.
        </Property>
        <Property name="'edgeAnchorLinks'">
          The top or bottom of the current page. Its `href` is a fragment, `'#SCROLL_TO_TOP'`
          or `'#SCROLL_TO_BOTTOM'`.
        </Property>
        <Property name="'loginToWixLink'">
          The Wix login dialog. Its `href` resolves to a `https://users.wix.com/signin?` URL.
        </Property>
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property
    name="appIds"
    type="string[]"
    description="Limits the link to specific Wix apps by app ID, as an array of GUIDs. Applies only to pageLink and dynamicPageLink."
  />
  <Property
    name="hideInnerRoute"
    type="boolean"
    description="For a dynamicPageLink, hides inner routes so the Wix user selects only a top-level page. The resolved link then holds only the page prefix, without the inner-route suffix."
  />
</PropertyList>
:::
:::Context-item
Declare it as a context item when your component supplies the link to descendant
components. It takes just `dataType` and `displayName`:

```json
{
  "ctaLink": {
    "dataType": "link",
    "displayName": "Call to Action"
  }
}
```
:::
:::Function-parameter-and-return
Declare it on a function when the function accepts or returns a link. A parameter accepts
the options that follow. A return takes only `dataType`:

```json
{
  "parameters": [
    {
      "dataType": "link",
      "displayName": "Call to Action",
      "link": { "linkTypes": ["externalLink", "pageLink"] }
    }
  ],
  "returns": { "dataType": "link" }
}
```

#### Options

A `link` parameter accepts the following options:

<PropertyList bordered>
  <Property
    name="linkTypes"
    type="LinkType[]"
    description="The kinds of link the Wix user may choose. Defaults to all of them."
  >
    <ExpandableSection name="LinkType values">
      <PropertyList>
        <Property name="'externalLink'">
          Another website. For example, `'https://example.com'`.
        </Property>
        <Property name="'pageLink'">
          Another page on the site. Its `href` resolves to the page's URL, such as `'/about'`.
        </Property>
        <Property name="'anchorLink'">
          An item on the current page. Its `href` resolves to the page URL plus the item's
          fragment, such as `'/about#team'`.
        </Property>
        <Property name="'emailLink'">
          An email address. For example, `'mailto:hello@example.com'`.
        </Property>
        <Property name="'phoneLink'">
          A phone number. For example, `'tel:+15551234567'`.
        </Property>
        <Property name="'dynamicPageLink'">
          A Wix app page resolved at runtime. Its `href` resolves to the app route, such as
          `'/blog/my-post'`. When only the top-level route is known, it stays a partial link,
          with `href` holding the router prefix and `pageRole` set.
        </Property>
        <Property name="'whatsAppLink'">
          A WhatsApp conversation. Its `href` resolves to a `https://api.whatsapp.com/send?phone=`
          URL.
        </Property>
        <Property name="'documentLink'">
          A document hosted by Wix, such as a PDF. Its `href` resolves to a URL to the hosted
          file.
        </Property>
        <Property name="'popupLink'">
          A lightbox on the site. Its `href` resolves to the current page URL with a `?popup=`
          query.
        </Property>
        <Property name="'addressLink'">
          An address on a map. Its `href` resolves to a Google Maps `http://maps.google.com/maps?daddr=`
          URL.
        </Property>
        <Property name="'edgeAnchorLinks'">
          The top or bottom of the current page. Its `href` is a fragment, `'#SCROLL_TO_TOP'`
          or `'#SCROLL_TO_BOTTOM'`.
        </Property>
        <Property name="'loginToWixLink'">
          The Wix login dialog. Its `href` resolves to a `https://users.wix.com/signin?` URL.
        </Property>
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property
    name="appIds"
    type="string[]"
    description="Limits the link to specific Wix apps by app ID, as an array of GUIDs. Applies only to pageLink and dynamicPageLink."
  />
  <Property
    name="hideInnerRoute"
    type="boolean"
    description="For a dynamicPageLink, hides inner routes so the Wix user selects only a top-level page. The resolved link then holds only the page prefix, without the inner-route suffix."
  />
</PropertyList>
:::
::::