guide/content/helpers/link.slim
---
title: Link helpers
---
markdown:
In addition to the components, this gem also comes with link helpers that are
often reimplemented across projects.
== render('/partials/example.*',
caption: "Regular link",
code: govuk_link_to_normal) do
markdown:
Regular links are just plain [anchor elements][0]
with the `govuk-link` class.
[0]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
== render('/partials/example.*',
caption: "Inverse hyperlink",
code: govuk_link_to_inverse,
inverse: true) do
p.govuk-body
| Use inverse hyperlinks on dark backgrounds.
== render('/partials/example.*',
caption: "Other link styles",
code: govuk_link_other_styles)
== render('/partials/example.*',
caption: "Links with visually hidden text",
code: govuk_link_with_visually_hidden_text) do
markdown:
When space is limited we sometimes rely on the link's position to provide
context about its target. An example of this is in admin interfaces where rows
in a table often have a 'View' link, or a 'Delete' button.
Omitting the extra text entirely leaves users of assistive technologies like
screen readers at a disadvantage, as they can't infer that context. We can
solve this problem using visually hidden text that isn't visible on the screen
but will be read out by screen readers.
The keyword arguments automatically add a space between the visually
hidden and regular text.
== render('/partials/example.*',
caption: "Links that open in a new tab",
code: govuk_link_to_new_tab) do
markdown:
You can use the `new_tab` parameter to automatically set the `target` and
`rel` [attributes as suggested by the design system][0].
When the link text is passed in as a string argument, 'opens in new tab' is
added to the end automatically. No suffix is added when the helper is used
in block mode.
The default text can be set using the `default_link_new_tab_text` configuration option
and it can be suppressed by setting it to an empty string.
If you don't want any extra text to be rendered you suppress the behaviour
with `new_tab: ""`.
[0]: https://design-system.service.gov.uk/styles/links/#opening-links-in-a-new-tab
hr.govuk-section-break.govuk-section-break--xl.govuk-section-break--visible
== render('/partials/example.*',
caption: "Class helpers",
code: govuk_link_classes_multiple) do
p.govuk-body
markdown:
Rails has [lots of link helpers][0]
and only the most frequently used are wrapped by this library. If you need
to use another variant, like `link_to_if`, you can use the
`govuk_link_classes` and `govuk_button_classes`
helpers to ensure the correct classes are assigned.
When no arguments are provided to `govuk_link_classes`, only
the default `govuk-link` will be added. Alternate styles
can be passed in as a snake cased array of variants.
[0]: #{rails_docs_url_helper}