# Work with links

It's best practice to have links in your site to other pages and external sources. But how do you do this? Here, we'll go through how links can be configured in Studio, how the API hub delivers them, and how you can use links in the frontend.

## Studio

To allow a Studio user to configure a link, a field of type `reference` or `node` (which is the legacy name for a page folder) needs to be added to a Frontend component schema. The difference between `reference` and `node` is that the first one gives the user a choice between internal and external links, while the latter only allows internal links to page folders.

Below is an example Frontend component schema that has 3 fields that show how the data is configured:

```json title="schema.json"
{
  "tasticType": "example/links-references",
  "name": "Links and references example",
  "icon": "anchor",
  "category": "general",
  "schema": [
    {
      "name": "Configuration",
      "fields": [
        {
          "label": "A link reference",
          "field": "aLinkReferenceField",
          "type": "reference"
        },
        {
          "label": "A page folder reference",
          "field": "aPageFolderReferenceField",
          "type": "reference"
        },
        {
          "label": "A page folder link",
          "field": "aPageFolderField",
          "type": "node"
        }
      ]
    }
  ]
}
```

The example shows 3 fields to see the different representations of a reference in the API hub further down this article.

When you preview the above JSON in the schema editor, you can see how each would display in the component settings:

![Rendered preview of the schema.json example](https://docs.commercetools.com/frontend-development/images/migrated/ea2eaf2-Working_with_links_example.png)

## API hub data

Once configured, the Frontend component data provided to you by the API hub follows the TypeScript interfaces `ReferenceValue` (for `reference` fields) and `PageFolderValue`:

```json title="Reference with external link"
"aLinkReferenceField": {
  "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\LinkReferenceValue",
  "link": "https://example.com",
  "openInNewWindow": false,
  "type": "link"
}
```

A reference always contains its `type` (selected in the Studio) and if the link is expected to `openInNewWindow`. For a `LinkReferenceValue`, the `link` property holds the target URL (relative or absolute).

```json title="Reference to a page folder"
"aPageFolderReferenceField": {
  "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\PageFolderReferenceValue",
  "openInNewWindow": false,
  "pageFolder": {
    "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\PageFolderValue",
    "_urls": {
      "de_CH": "/sub-page",
      "de_LI": "/sub-page",
      "fr_CH": "/sub-page",
      "it_CH": "/sub-page"
    },
    "configuration": {
      "path": "sub-page",
      "pathTranslations": []
    },
    "name": "Sub",
    "pageFolderId": "8733ddef122e2c9769a2dd441f11a7b9"
  },
  "type": "page-folder"
}
```

A `PageFolderReferenceValue` holds a `pageFolder` instead of the `link`. This is of type `PageFolderValue` and contains information about the page folder, such as its `name`. It also holds the special field `_urls`, which contains a map of all defined locales to the corresponding path for the page folder. This map allows you to link to the folder in different languages in a multi-language project.

The `PageFolderValue` is meant to contain a property `_url`, which holds the path of the page folder in the current locale so that you don't need to care for locale resolution in the frontend. This feature is still to be implemented.

If you use a `node` type field, the value received is only the inner `PageFolderValue`, for example:

```json title="Page folder field"
"aPageFolderField": {
  "_type": "Frontastic\\Catwalk\\NextJsBundle\\Domain\\Api\\TasticFieldValue\\PageFolderValue",
  "_urls": {
    "de_CH": "/",
    "de_LI": "/",
    "fr_CH": "/",
    "it_CH": "/"
  },
  "configuration": {
    "path": "/",
    "pathTranslations": []
  },
  "name": "Main",
  "pageFolderId": "2484aae237475b21de02bc1e2d13b3c4"
}
```

## Links in the frontend

Link values generated by the API hub are meant to be used as they're with the Next.js router, for example:

```typescript title="Routing to a page folder"
import Link from 'next/link';

const SimpleLink: React.FC = ({ data }) => {
  return (
    <Link href={aPageFolderField.urls['de_CH']}>{aPageFolderValue.name}</Link>
  );
};
```

## Link to dynamic pages

For dynamic pages, which have been implemented using the [dynamic page handler extension point](/frontend-development/developing-a-dynamic-page-extension.md), we recommend using the same `_url` (and probably `_urls`) property scheme shown further up in this article. With that, there's a single unique scheme for handling links in the frontend, and link generation is centrally handled in the backend.

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Manage project configuration](/frontend-development/api-hub-configuration.md)
- [Next page: Schemas](/frontend-development/schemas.md)
- [Search documentation and API specs](/search.md)