Generates a link for live and href navigation.

Attributes

• id (:any) - Defaults to nil.

• class (:any) - Defaults to nil.

• navigate (:string) - Navigates from a LiveView to a new LiveView. The browser page is kept, but a new LiveView process is mounted and its content on the page is reloaded. It is only possible to navigate between LiveViews declared under the same router Phoenix.LiveView.Router.live_session/3. Otherwise, a full browser redirect is used.

• patch (:string) - Patches the current LiveView. The handle_params callback of the current LiveView will be invoked and the minimum content will be sent over the wire, as any other LiveView diff.

• href (:any) - Uses traditional browser navigation to the new location. This means the whole page is reloaded on the browser.

• replace (:boolean) - When using :patch or :navigate, should the browser's history be replaced with pushState?

  Defaults to false.

• method (:string) - The HTTP method to use with the link. In case the method is not get, the link is generated inside the form which sets the proper information. In order to submit the form, JavaScript must be enabled in the browser.

  Defaults to "get".

• csrf_token (:any) - A boolean or custom token to use for links with an HTTP method other than get. Defaults to true.

• Global attributes are accepted. Additional HTML attributes added to the a tag. Supports all globals plus: ["download", "hreflang", "referrerpolicy", "rel", "target", "type", "disabled"].

Slots

• inner_block (required) - The content rendered inside of the a tag.

Examples

<.dm_link href="/">Regular anchor link</.dm_link>

<.dm_link navigate={Routes.page_path(@socket, :index)} class="underline">home</.dm_link>

<.dm_link navigate={Routes.live_path(@socket, MyLive, dir: :asc)} replace={false}>
  Sort By Price
</.dm_link>

<.dm_link patch={Routes.page_path(@socket, :index, :details)}>view details</.dm_link>

<.dm_link href={URI.parse("https://elixir-lang.org")}>hello</.dm_link>

<.dm_link href="/the_world" method={:delete} data-confirm="Really?">delete</.dm_link>

JavaScript dependency

In order to support links where :method is not :get or use the above data attributes, Phoenix.HTML relies on JavaScript. You can load priv/static/phoenix_html.js into your build tool.

Data attributes

Data attributes are added as a keyword list passed to the data key. The following data attributes are supported:

• data-confirm - shows a confirmation prompt before generating and submitting the form when :method is not :get.

Overriding the default confirm behaviour

phoenix_html.js does trigger a custom event phoenix.link.click on the clicked DOM element when a click happened. This allows you to intercept the event on its way bubbling up to window and do your own custom logic to enhance or replace how the data-confirm attribute is handled. You could for example replace the browsers confirm() behavior with a custom javascript implementation:

// listen on document.body, so it's executed before the default of
// phoenix_html, which is listening on the window object
document.body.addEventListener('phoenix.link.click', function (e) {
  // Prevent default implementation
  e.stopPropagation();
  // Introduce alternative implementation
  var message = e.target.getAttribute("data-confirm");
  if(!message){ return true; }
  vex.dialog.confirm({
    message: message,
    callback: function (value) {
      if (value == false) { e.preventDefault(); }
    }
  })
}, false);

Or you could attach your own custom behavior.

window.addEventListener('phoenix.link.click', function (e) {
  // Introduce custom behaviour
  var message = e.target.getAttribute("data-prompt");
  var answer = e.target.getAttribute("data-prompt-answer");
  if(message && answer && (answer != window.prompt(message))) {
    e.preventDefault();
  }
}, false);

The latter could also be bound to any click event, but this way you can be sure your custom code is only executed when the code of phoenix_html.js is run.

CSRF Protection

By default, CSRF tokens are generated through Plug.CSRFProtection.