Correct and idiomatic ways to use the <mds-url-view> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Minimal Embed Inside a Modal

The most common use: pass only the required src and place the component in the window slot of mds-modal. The header title falls back to the hostname extracted from src.

<mds-modal id="modal-anteprima" position="center" opened>
  <mds-url-view
    slot="window"
    class="max-w-screen-tablet w-full"
    src="https://www.comune.bologna.it/"
  ></mds-url-view>
</mds-modal>

Custom Header Label

Override the auto-derived hostname with a human-readable title via label. Use this when the URL is not self-describing or when the UI language differs from the domain name.

<mds-modal id="modal-modulo" position="center" opened>
  <mds-url-view
    slot="window"
    class="max-w-screen-tablet w-full"
    src="https://forms.example.com/richiesta-certificato"
    label="Modulo di richiesta certificato"
  ></mds-url-view>
</mds-modal>

Custom Header Icon

Provide icon with an icon slug to replace the default “explore” glyph with a context-appropriate symbol.

<mds-modal id="modal-libro" position="center" opened>
  <mds-url-view
    slot="window"
    class="max-w-screen-tablet w-full"
    src="https://books.example.com/catalogo"
    label="Catalogo libri"
    icon="mgg/google-book-large"
  ></mds-url-view>
</mds-modal>

Eager Loading

Set loading="eager" when the content should start fetching immediately - for example, when the modal is already open on page load and the iframe is immediately visible.

<mds-modal position="center" opened>
  <mds-url-view
    slot="window"
    src="https://dashboard.example.com/"
    label="Dashboard"
    loading="eager"
  ></mds-url-view>
</mds-modal>

Reacting to the Close Event

Listen for mdsUrlViewClose to update application state when the user clicks the dismiss control. When the component is inside mds-modal the ancestor modal is also closed automatically, but you may still need to sync your own state.

<mds-modal id="modal-url" position="center" opened>
  <mds-url-view
    id="url-view"
    slot="window"
    src="https://servizi.example.it/portale"
    label="Portale servizi"
  ></mds-url-view>
</mds-modal>

<script>
  document.querySelector('#url-view').addEventListener('mdsUrlViewClose', () => {
    // aggiorna lo stato dell'applicazione
    appState.urlViewOpen = false;
  });
</script>

Styling Customization

Style the component only through its documented --mds-url-view-* CSS custom properties. Set them on the host or on a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.anteprima-documento mds-url-view {
  --mds-url-view-background: rgb(var(--magma-wash-base));
  --mds-url-view-color: rgb(var(--magma-text-default));
  --mds-url-view-radius: var(--magma-radius-lg);
  --mds-url-view-shadow: var(--shadow-xl);
  --mds-url-view-header-shadow: var(--shadow-md-sharp);
}