Link plugin

The link plugin allows a user to link external resources such as website URLs, to selected text in their document.

It adds two toolbar buttons called link and unlink and three menu items called link, unlink and openlink. The toolbar button and menu item called link are included in TinyMCE’s default configuration. The link menu item can be found in the Insert menu.

The link plugin also includes a context menu and context toolbar. The context toolbar can be configured using the link_context_toolbar and link_quicklink options documented below.

Basic setup

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link'
});

Options

These settings affect the execution of the link plugin. Predefined links, targets, and more can be specified here.

This option allows you to set a default target value for links when inserting/editing a link via the link dialog. If the value of link_default_target matches a value specified by the link_target_list option, that item will be set as the default item for the targets dropdown in the link dialog.

This option also applies to the autolink plugin.

Type: String

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_default_target: '_blank'
});

Set whether TinyMCE should prepend a http:// prefix if the supplied URL does not contain a protocol prefix.

  • false: Users are prompted to prepend http:// when the URL entered starts with www and does not have a protocol. Other URLs are added without prompt.

  • true: URLs are assumed to be external. Users are prompted to prepend a http:// prefix when the protocol is not specified.

  • 'http': URLs are assumed to be external. URLs without a protocol prefix are prepended a http:// prefix.

  • 'https': URLs are assumed to be external. URLs without a protocol prefix are prepended a https:// prefix.

Type: Boolean or String

Default value: false

Possible values: true, false, 'http', 'https'

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_assume_external_targets: true
});

The link_class_list option allows you to specify a list of classes for the link dialog. These classes will appear in a dropdown menu in the link dialog. Each class must be defined as an object with a title and a value. For example: { title: 'Cat', value: 'cat' }. When the dialog is submitted, the value of the selected class item from the dropdown will be set as the link’s class.

Type: Array

Default value: []

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_class_list: [
    { title: 'None', value: '' },
    { title: 'External Link', value: 'ext_link' },
    { title: 'Internal Support Link', value: 'int_sup_link' },
    { title: 'Internal Marketing Link', value: 'int_mark_link' },
    { title: 'Other Internal Link', value: 'int_other_link' }
  ]
});

To create a nested list, replace value with menu to add the top level of the list, then provide an array of items.

For example:

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_class_list: [
    { title: 'None', value: '' },
    { title: 'External Link', value: 'ext_link' },
    { title: 'Internal Links',
      menu: [
        { title: 'Internal Support Link', value: 'int_sup_link' },
        { title: 'Internal Marketing Link', value: 'int_mark_link' },
        { title: 'Other Internal Link', value: 'int_other_link' }
      ]
    }
  ]
});

By default it is not possible to open links directly from the editor. Setting link_context_toolbar to true will enable a context toolbar that will appear when the user’s cursor is within a link. This context toolbar contains fields to modify, remove and open the selected link. External links will be opened in a separate tab, while relative links scroll to a target within the editor (if the target is found).

This context toolbar is the same as the context toolbar mentioned in the Link plugin - link_quicklink documentation.

Type: Boolean

Default value: false

Possible values: true, false

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_context_toolbar: true
});

This option allows you to set a default protocol for links when inserting/editing a link via the link dialog. The protocol will apply to any links where the protocol has not been specified and the prefix prompt has been accepted.

This option also applies to the autolink plugin.

Type: String

Default value: 'https'

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_default_protocol: 'http'
});

This option lets you specify a predefined list of links for the link dialog. These links are added to a drop-down list in the link dialog. When a list item is selected, the dialog will be populated with the relevant data. This is useful if your users need to regularly link to the same sources.

There are multiple ways to specify how to get the data for the link list, but all methods rely on the returned data containing an array of link items. A link item is an object with a title and a value. For example: { title: 'My page 1', value: 'https://www.tiny.cloud' }.

Type: String, Array or Function

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: [
    { title: '{companyname} Home Page', value: '{companyurl}' },
    { title: '{companyname} Blog', value: '{companyurl}/blog' },
    { title: '{productname} Documentation', value: '{companyurl}/docs/' },
    { title: '{productname} on Stack Overflow', value: '{communitysupporturl}' },
    { title: '{productname} GitHub', value: 'https://github.com/tinymce/' }
  ]
});

To create a nested list, replace value with menu to add the top level of the list, then provide an array of items.

For example:

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: [
    { title: '{companyname} Home Page', value: '{companyurl}' },
    { title: '{companyname} Blog', value: '{companyurl}/blog' },
    { title: '{productname} Support resources',
      menu: [
        { title: '{productname} Documentation', value: '{companyurl}/docs/' },
        { title: '{productname} on Stack Overflow', value: '{communitysupporturl}' },
        { title: '{productname} GitHub', value: 'https://github.com/tinymce/' }
      ]
    }
  ]
});

You can also configure a URL with JSON data. The JSON data must use the same format as above.

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: '/mylist.php'
});

Example of a custom asynchronous callback function

link_list can also take a function that is called when the link dialog is opened. TinyMCE passes this function a success callback function, which should be passed an array of link items. This allows for asynchronous and dynamic generation of the list of links.

The following is an example of how link_list can be used with a callback function. fetchLinkList could be replaced with any function that returns an array of link items. It can be used to generate a list of link items based on:

  • Data retrieved from a database.

  • The current editor content.

  • The current user.

const fetchLinkList = () => [
  { title: 'My page 1', value: 'https://www.tiny.cloud' },
  { title: 'My page 2', value: 'https://about.tiny.cloud' }
];

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: (success) => { // called on link dialog open
    const links = fetchLinkList(); // get link_list data
    success(links); // pass link_list data to {productname}
  }
});

This options allows you disable the link title input field in the link dialog.

Type: Boolean

Default value: true

Possible values: true, false

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_title: false
});

This option changes the behaviour of the CTRL + K shortcut. By default, pressing CTRL + K will open the link dialog. If link_quicklink is set to true, pressing CTRL + K will instead open the link context toolbar. If the cursor is within an existing link, this context toolbar will contain fields for modifying, removing and opening the selected link. If not, the context toolbar allows for the quick insertion of a link.

This context toolbar is the same as the context toolbar mentioned in the link_context_toolbar documentation above.

Type: Boolean

Default value: false

Possible values: true, false

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_quicklink: true
});

This option lets you specify a list of rel values for the link dialog. These values gets applied to the rel attribute. Each rel item must be defined as an object with a title and a value. For example: { title: 'No Referrer', value: 'noreferrer' }. When the dialog is submitted, the value of the selected rel item will be set as the link’s rel attribute.

Type: Array

Default value: []

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_rel_list: [
    { title: 'No Referrer', value: 'noreferrer' },
    { title: 'External Link', value: 'external' }
  ]
});

The link_target_list option lets you specify a list of named targets for the link dialog. These targets will appear in a dropdown menu in the link dialog. Each target must be defined as an object with a title and a value. For example: { title: 'Same page', value: '_self' }. When the dialog is submitted, the value of the selected target item will be set as the link’s target attribute.

If link_default_target is also configured and its value matches a value specified by link_target_list, that item will be set as the default item for the targets dropdown in the link dialog.

Type: Boolean or Array

Default value:

[
  { text: 'Current window', value: '' },
  { text: 'New window', value: '_blank' }
]

Example: adding a _parent target to the dropdown list

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_target_list: [
    { title: 'None', value: '' },
    { title: 'Same page', value: '_self' },
    { title: 'New page', value: '_blank' },
    { title: 'Parent frame', value: '_parent' }
  ]
});

To disable the option dialog, set link_target_list to false.

Example: turning off the target list dialog

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'link',
  toolbar: 'link',
  link_target_list: false
});

Toolbar buttons

The Link plugin provides the following toolbar buttons:

Toolbar button identifier Description

link

Creates/Edits links within the editor.

openlink

Opens the selected link in a new tab.

unlink

Removes links from the current selection.

These toolbar buttons can be added to the editor using:

The Link plugin provides the following menu items:

Menu item identifier Default Menu Location Description

link

Insert

Opens the link dialog.

openlink

Not Applicable

Opens the selected link in a new tab.

unlink

Not Applicable

Removes the hyperlink from the selected text.

These menu items can be added to the editor using:

Commands

The Link plugin provides the following TinyMCE command.

Command Description

mceLink

Opens the Link or Quicklink Dialog at the current cursor position or for the current selection.
Example
tinymce.activeEditor.execCommand('mceLink');