Skip to content

Kirby 4.2.0

    Search by Algolia

    Link

    Use the link field to create links to external URLs, internal pages, files, email addresses and telephone numbers. The link field is also used in the link dialogs of the writer and textarea fields.

    Field properties

    Name Type Default Description
    autofocus bool – Sets the focus on this field when the form loads. Only the first field with this label gets
    default – Default value for the field, which will be used when a page/file/user is created
    disabled bool – If true, the field is no longer editable and will not be saved
    help – Optional help text below the field
    label – The field label can be set as string or associative array with translations
    options array –
    required bool – If true, the field has to be filled in correctly to be saved.
    translate bool true If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
    when – Conditions when the field will be shown (since 3.1.0)
    width string 1/1 The width of the field in the field grid. Available widths: 1/1, 1/2, 1/3, 1/4, 2/3, 3/4

    Example

    fields:
  link:
    type: link
    • url
    • page
    • file
    • email
    • tel
    • anchor
    • custom
    Since 4.1.1

    The custom link type is not enabled by default as it cannot validate the entered URL. See the section on the custom link type below for more.

    If an icon has been defined in the page's blueprint, it will be used in the page selector.

    The custom link type allows to enter arbitrary links, e.g. relative links or deeplinks to external apps with custom protocols.

    Because of its flexibility, Kirby cannot know whether the entered link is valid and safe. It is therefore your responsibility to check if the link conforms to the format for your use case.

    Using the custom link type without additional validation or sanitization can lead to security attacks such as cross-site scripting (XSS). Only enable this link type if you have adequate protections in place or if such protections are not needed in your use case.

    With the options property you can customize the link types offered by the field:

    fields:
  link:
    type: link
    options:
      - page
      - anchor

    Use in templates/snippets

    Use the toUrl() method to convert any type of link to a valid URL:

    <a href="<?= $page->link()->toUrl() ?>"><?= $page->link() ?></a>

    Adding target, link text etc.

    The link field does one job and one job only: It stores a link. If you need additional metadata such as a target, link text, class names etc., you can wrap the link field within an object field:

    fields:
  linkObject:
    type: object
    fields:
      link:
        type: link
      linkText:
         type: text
      target:
        type: toggle
        text: Open in new window?
      classnames:
         type: text

    Then create a snippet that you can re-use across your site for all such wrapped link fields. Here is a basic example for you to extend according to your requirements:

    <?php $linkObject = $page->linkObject()->toObject(); ?>
<a
    href="<?= $linkObject->link()->toUrl() ?>"
    <?= $linkObject->target()->toBool() === true ? 'target="_blank"' : '' ?>
    <?= $linkObject->classnames()->isNotEmpty() ? 'class="' . $linkObject->classnames() . '"' : '' ?>
>
  <?= $linkObject->linkText()->or($linkObject->link()) ?>
</a>