# LinkConfig

interface

The configuration of the [link feature](module_link_link-Link.md).

```typescript
ClassicEditor
	.create( {
		link:  ... // Link feature configuration.
	} )
	.then( ... )
	.catch( ... );
```

See [all editor options](module_core_editor_editorconfig-EditorConfig.md).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/src/linkconfig.ts#L26)

<a id="properties">

## Properties

<a id="member-addTargetToExternalLinks">

### `addTargetToExternalLinks?: boolean`

When set to `true`, the `target="blank"` and `rel="noopener noreferrer"` attributes are automatically added to all external links in the editor. "External links" are all links in the editor content starting with `http`, `https`, or `//`.

```typescript
ClassicEditor
	.create( {
		link: {
			addTargetToExternalLinks: true
		}
	} )
	.then( ... )
	.catch( ... );
```

Internally, this option activates a predefined [automatic link decorator](#member-decorators) that extends all external links with the `target` and `rel` attributes.

**Note**: To control the `target` and `rel` attributes of specific links in the edited content, a dedicated [manual](module_link_linkconfig-LinkDecoratorManualDefinition.md) decorator must be defined in the [`config.link.decorators`](#member-decorators) array. In such scenario, the `config.link.addTargetToExternalLinks` option should remain `undefined` or `false` to not interfere with the manual decorator.

**Note**: If a manual decorator that handles the `target` attribute is already defined in the [`config.link.decorators`](#member-decorators) array, the automatic decorator will be overridden by the manual decorator, but only when the manual decorator is activated for the given link.

It is possible to add other [automatic](module_link_linkconfig-LinkDecoratorAutomaticDefinition.md) or [manual](module_link_linkconfig-LinkDecoratorManualDefinition.md) link decorators when this option is active.

More information about decorators can be found in the [decorators configuration](#member-decorators) reference.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/src/linkconfig.ts#L127)

Defaults to `false`

<a id="member-allowCreatingEmptyLinks">

### `allowCreatingEmptyLinks?: boolean`

When set to `true`, the form will accept an empty value in the URL field, creating a link with an empty `href` (`<a href="">`).

```typescript
ClassicEditor
	.create( {
		link: {
			allowCreatingEmptyLinks: true
		}
	} )
	.then( ... )
	.catch( ... );
```

**NOTE:** This option only adds form validation. If a link with an empty `href` is loaded into the editor, it will be left as-is.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/src/linkconfig.ts#L90)

Defaults to `false`

<a id="member-allowedProtocols">

### `allowedProtocols?: Array<string>`

This is a protocols whitelist that can be used in links, defined as an array of strings. When not set, the editor will use a default list of allowed protocols.

**Note:** Use this with caution and at your own risk - adding unsafe protocols like `javascript:` can result in serious security vulnerabilities!

```typescript
ClassicEditor
	.create( {
		link: {
			allowedProtocols: [ 'http', 'https', 'ftp', 'tel', 'mailto', 'ssh' ]
		}
	} )
	.then( ... )
	.catch( ... );
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/src/linkconfig.ts#L70)

<a id="member-decorators">

### `decorators?: Record<string, LinkDecoratorDefinition>`

Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are two types of link decorators:

* [Automatic](module_link_linkconfig-LinkDecoratorAutomaticDefinition.md) – They match links against pre–defined rules and manage their attributes based on the results.
* [Manual](module_link_linkconfig-LinkDecoratorManualDefinition.md) – They allow users to control link attributes individually, using the editor UI.

Link decorators are defined as objects with key-value pairs, where the key is the name provided for a given decorator and the value is the decorator definition.

The name of the decorator also corresponds to the [text attribute](../framework/architecture/editing-engine.md#text-attributes) in the model. For instance, the `isExternal` decorator below is represented as a `linkIsExternal` attribute in the model.

```typescript
ClassicEditor
	.create( {
		link: {
			decorators: {
				isExternal: {
					mode: 'automatic',
					callback: url => url.startsWith( 'http://' ),
					attributes: {
						target: '_blank',
						rel: 'noopener noreferrer'
					}
				},
				isDownloadable: {
					mode: 'manual',
					label: 'Downloadable',
					attributes: {
						download: 'file.png',
					}
				},
				// ...
			}
		}
	} )
	.then( ... )
	.catch( ... );
```

To learn more about the configuration syntax, check out the [automatic](module_link_linkconfig-LinkDecoratorAutomaticDefinition.md) and [manual](module_link_linkconfig-LinkDecoratorManualDefinition.md) decorator option reference.

**Warning:** Currently, link decorators work independently of one another and no conflict resolution mechanism exists. For example, configuring the `target` attribute using both an automatic and a manual decorator at the same time could end up with quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.

**Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator dedicated for that purpose which can be enabled by turning a single option on. Check out the [`config.link.addTargetToExternalLinks`](#member-addTargetToExternalLinks) configuration description to learn more.

See also the [link feature guide](../features/link.md#custom-link-attributes-decorators) for more information.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/src/linkconfig.ts#L186)

<a id="member-defaultProtocol">

### `defaultProtocol?: string`

When set, the editor will add the given protocol to the link when the user creates a link without one. For example, when the user is creating a link and types `ckeditor.com` in the link form input, during link submission the editor will automatically add the `http://` protocol, so the link will look as follows: `http://ckeditor.com`.

The feature also provides email address auto-detection. When you submit `hello@example.com`, the plugin will automatically change it to `mailto:hello@example.com`.

```typescript
ClassicEditor
	.create( {
		link: {
			defaultProtocol: 'http://'
		}
	} )
	.then( ... )
	.catch( ... );
```

**NOTE:** If no configuration is provided, the editor will not auto-fix the links.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/src/linkconfig.ts#L49)

<a id="member-toolbar">

### `toolbar?: Array<string>`

Items to be placed in the link contextual toolbar.

Assuming that you use the [`LinkUI`](module_link_linkui-LinkUI.md) feature, the following toolbar items will be available in [`ComponentFactory`](module_ui_componentfactory-ComponentFactory.md):

* `'linkPreview'`,
* `'editLink'`,
* `'linkProperties'`
* `'unlink'`.

The default configuration for link toolbar is:

```typescript
const linkConfig = {
	toolbar: [ 'linkPreview', '|', 'editLink', 'linkProperties', 'unlink' ]
};
```

The `linkProperties` toolbar item is only available when at least one manual decorator is defined in the [decorators configuration](#member-decorators).

Of course, the same buttons can also be used in the [main editor toolbar](module_core_editor_editorconfig-EditorConfig.md#member-toolbar).

Read more about configuring the toolbar in [`toolbar`](module_core_editor_editorconfig-EditorConfig.md#member-toolbar).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/src/linkconfig.ts#L215)

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)