caption: link
created: 20131024141900000
modified: 20260206131722044
tags: Widgets
title: LinkWidget
type: text/vnd.tiddlywiki

The `link` widget generates links to tiddlers. (Use the HTML `<a>` element to generate external links).

! Content and Attributes

The content of the link widget is rendered within the `<a>` tag representing the link. If the content is empty then the title of the target tiddler is rendered as the default, for example:

* `<$link/>` is equivalent to `<$link to=<<currentTiddler>>><$view field="title"/></$link>`
* `<$link to="HelloThere"/>` is equivalent to `<$link to="HelloThere">HelloThere</$link>`

|!Attribute |!Description |
|to |The title of the target tiddler for the link (defaults to the [[current tiddler|Current Tiddler]]) |
|aria-label |Optional accessibility label |
|role |<<.from-version "5.4.0">> Optional [[ARIA role|https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles]] |
|tooltip |Optional tooltip WikiText |
|tabindex |Optional numeric [[tabindex|https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/tabIndex]] |
|draggable |"yes" to enable the link to be draggable (defaults to "yes") |
|tag |Optional tag to override the default "a" element |
|class|Optional CSS classes //in addition to// the default classes (see below)|
|overrideClass|<<.from-version "5.1.16">> Optional CSS classes //instead of// the default classes |
|data-* |<<.from-version "5.3.2">> Optional [[data attributes|https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes]] to be assigned to the HTML element |
|style.* |<<.from-version "5.3.2">> Optional [[CSS properties|https://developer.mozilla.org/en-US/docs/Web/CSS/Reference]] to be assigned to the HTML element |
|aria-* |<<.from-version "5.4.0">> Optional [[ARIA attributes|https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes]] to be assigned to the HTML element |
|startactions |<<.from-version "5.4.0">> Optional action string that gets invoked when ''dragging starts''. The <<.var actionTiddler>> variable is available in this action.|
|endactions |<<.from-version "5.4.0">> Optional action string that gets invoked when ''dragging ends''. The <<.var actionTiddler>> variable is available in this action. |

The draggable functionality is equivalent to using the DraggableWidget with the ''tiddler'' attribute set to the link target.

The default value of the tooltip attribute is supplied by the <<.vlink tv-wikilink-tooltip>> variable.

This means that you can control the text of a link tooltip in several ways:

```
<$link to="HelloThere" tooltip="Custom tooltip">Link 1</$link>

<$link to="HelloThere" tooltip="Another tooltip">{{$:/core/icon}}</$link>

<$set name="tv-wikilink-tooltip" value="I'm a link to {{!!title}}">
<$link to="HelloThere">Link 2</$link>
</$set>

```

Renders as:

<$link to="HelloThere" tooltip="Custom tooltip">Link 1</$link>

<$link to="HelloThere" tooltip="Another tooltip">{{$:/core/icon}}</$link>

<$set name="tv-wikilink-tooltip" value="I'm a link to {{!!title}}">
<$link to="HelloThere">Link 2</$link>
</$set>

Note that the tooltip is rendered with the current tiddler set to the target of the link.

A useful convention is to set the tooltip like this:

```
\define tv-wikilink-tooltip()
<$transclude field="tooltip"><$transclude field="title"/></$transclude>
\end
```

This causes the tooltip to be the ''tooltip'' field of the target tiddler. If the field isn't present, then the title is used instead.

! Action Variables

<<.from-version "5.4.0">> The <<.var actionTiddler>> variable is available to <<.param startaction>> and <<.param endaction>>.

To see all variables available to an action you can use this code and see the variables in the browser dev-console (F12)

<<wikitext-example-without-html """\procedure endActions()
<$action-log/>
\end

<$link to=HelloThere endactions=<<endActions>>>drag me!</$link>
""">>

! CSS Classes

The link widget automatically determines and applies the following classes to links:

* `tc-tiddlylink` - applied to ''all'' links
* `tc-tiddlylink-external` - applied to external, non-tiddler links
* `tc-tiddlylink-internal` - applied to tiddler links
* `tc-tiddlylink-missing` - applied to tiddler links where the target tiddler doesn't exist
* `tc-tiddlylink-resolves` - applied to tiddler links when the target tiddler does exist
* `tc-tiddlylink-shadow` - applied to tiddler links when the target is a shadow tiddler
** `tc-tiddlylink-shadow tc-tiddlylink-resolves` - applied to ''overwritten'' shadow tiddlers

Use the `class` attribute to specify additional css classes, or `overrideClass` to apply only that but not the above defaults, e.g. when used in a LinkCatcherWidget:

<<wikitext-example-without-html """*<$link class="example">Here</$link> the `example` class is added.
*<$link overrideClass="example">Here</$link> only the `example` class applies.
*<$link overrideClass="">Here</$link> no class is set.""">>

! `href` generation

The following process is used to generate the `href` attribute of the generated HTML `<a>` element:

# If <<.vlink tv-get-export-link>> is defined it is invoked to convert the target tiddler title to the `href` value
#* In practice, only a [[JavaScript macro|Macros]] can be used
# <<.from-version "5.1.15">> If <<.vlink tv-filter-export-link>> is defined it is interpreted as a filter that converts the target tiddler title to the `href` value
# If <<.vlink tv-wikilink-template>> is defined it is treated as a specialised macro body that can perform limited conversion of the target tiddler title to the `href` value
# Otherwise, the target tiddler title is URI encoded to create the `href`

! Configuration Variables

* <<.vlink tv-wikilinks>>
* <<.vlink tv-filter-export-link>>
* <<.vlink tv-wikilink-template>>
* <<.vlink tv-wikilink-tooltip>>
* <<.vlink tv-get-export-link>>