@ckeditor/ckeditor5-link

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any];

method afterInit

afterInit: () => void;

method init

init: () => void;

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof LinkEditing,
    typeof LinkUI,
    typeof AutoLink
];

property automaticDecorators

readonly automaticDecorators: AutomaticDecorators;

• An instance of the helper that ties together all that are used by the and the features.

property manualDecorators

readonly manualDecorators: Collection<ManualDecorator>;

• A collection of corresponding to the .

  You can consider it a model with states of manual decorators added to the currently selected link.

property value

value: string;

• The value of the 'linkHref' attribute if the start of the selection is located in a node with this attribute.

  Modifiers

  • @readonly

method execute

execute: (href: string, manualDecoratorIds?: Record<string, boolean>) => void;

• Executes the command.

  When the selection is non-collapsed, the linkHref attribute will be applied to nodes inside the selection, but only to those nodes where the linkHref attribute is allowed (disallowed nodes will be omitted).

  When the selection is collapsed and is not inside the text with the linkHref attribute, a new with the linkHref attribute will be inserted in place of the caret, but only if such element is allowed in this place. The _data of the inserted text will equal the href parameter. The selection will be updated to wrap the just inserted text node.

  When the selection is collapsed and inside the text with the linkHref attribute, the attribute value will be updated.

  # Decorators and model attribute management

  There is an optional argument to this command that applies or removes model brought by .

  Text attribute names in the model correspond to the entries in the . For every decorator configured, a model text attribute exists with the "link" prefix. For example, a 'linkMyDecorator' attribute corresponds to 'myDecorator' in the configuration.

  To learn more about link decorators, check out the documentation.

  Here is how to manage decorator attributes with the link command:

  const linkCommand = editor.commands.get( 'link' );
  
  // Adding a new decorator attribute.
  linkCommand.execute( 'http://example.com', {
  	linkIsExternal: true
  } );
  
  // Removing a decorator attribute from the selection.
  linkCommand.execute( 'http://example.com', {
  	linkIsExternal: false
  } );
  
  // Adding multiple decorator attributes at the same time.
  linkCommand.execute( 'http://example.com', {
  	linkIsExternal: true,
  	linkIsDownloadable: true,
  } );
  
  // Removing and adding decorator attributes at the same time.
  linkCommand.execute( 'http://example.com', {
  	linkIsExternal: false,
  	linkFoo: true,
  	linkIsDownloadable: false,
  } );

  **Note**: If the decorator attribute name is not specified, its state remains untouched.

  **Note**: removes all decorator attributes.

  execute

  Parameter href

  Link destination.

  Parameter manualDecoratorIds

  The information about manual decorator attributes to be applied or removed upon execution.

method refresh

refresh: () => void;

method restoreManualDecoratorStates

restoreManualDecoratorStates: () => void;

• Synchronizes the state of with the currently present elements in the model.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, any, any];

method init

init: () => void;

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof LinkImageEditing, typeof LinkImageUI];

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    'ImageEditing',
    'ImageUtils',
    typeof LinkEditing
];

method init

init: () => void;

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
    typeof LinkEditing,
    typeof LinkUI,
    'ImageBlockEditing'
];

method init

init: () => void;

property actionsView

actionsView: LinkActionsView;

• The actions view displayed inside of the balloon.

property formView

formView: any;

• The form view displayed inside the balloon.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any];

method destroy

destroy: () => void;

method init

init: () => void;

method execute

execute: () => void;

• Executes the command.

  When the selection is collapsed, it removes the linkHref attribute from each node with the same linkHref attribute value. When the selection is non-collapsed, it removes the linkHref attribute from each node in selected ranges.

  # Decorators

  If is specified, all configured decorators are removed together with the linkHref attribute.

  execute

method refresh

refresh: () => void;

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

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

  Internally, this option activates a predefined 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 decorator must be defined in the 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 or link decorators when this option is active.

  More information about decorators can be found in the reference.

  false

property 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:

  * – They match links against pre–defined rules and manage their attributes based on the results. * – 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 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 and 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 configuration description to learn more.

  See also the for more information.

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

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

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