CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

LinkConfig (link)

@ckeditor/ckeditor5-link/src/linkconfig

interface
See source

The configuration of the link feature.

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

See all editor options.

Filtering

Properties

  • addTargetToExternalLinks : boolean | undefined

    See source

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

    ClassicEditor
	.create( editorElement, {
		link: {
			addTargetToExternalLinks: true
		}
	} )
	.then( ... )
	.catch( ... );

    Internally, this option activates a predefined automatic link decorator 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 decorator must be defined in the config.link.decorators array. In such scenario, the config.link.addTargetToExternalLinks option should remain undefined or false to not interfere with the manual decorator.

    It is possible to add other automatic or manual link decorators when this option is active.

    More information about decorators can be found in the decorators configuration reference.

    Defaults to false

  • allowCreatingEmptyLinks : boolean | undefined

    See source

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

    ClassicEditor
	.create( editorElement, {
		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.

    Defaults to false

  • allowedProtocols : Array<string> | undefined

    See source

    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!

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

  • decorators : Record<string, LinkDecoratorDefinition> | undefined

    See source

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

    • Automatic – They match links against pre–defined rules and manage their attributes based on the results.
    • Manual – 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 in the model. For instance, the isExternal decorator below is represented as a linkIsExternal attribute in the model.

    ClassicEditor
	.create( editorElement, {
		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 and manual 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 configuration description to learn more.

    See also the link feature guide for more information.

  • defaultProtocol : string | undefined

    See source

    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.

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

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