Common incorrect uses of <mds-url-view>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Use a Raw <iframe> When Magma Chrome Is Needed

Reaching for a bare <iframe> skips the header, dismiss control, accessibility labels, keyboard handling, and modal integration that <mds-url-view> provides. Use the component instead.

<!-- INCORRECT -->
<mds-modal position="center" opened>
  <iframe slot="window" src="https://servizi.example.it/" style="width:100%;height:80vh;"></iframe>
</mds-modal>

<!-- CORRECT -->
<mds-modal position="center" opened>
  <mds-url-view
    slot="window"
    class="max-w-screen-tablet w-full"
    src="https://servizi.example.it/"
    label="Portale servizi"
  ></mds-url-view>
</mds-modal>

Do Not Omit src

src is the only required prop. Without it the iframe loads nothing, and the header title and the ARIA labels, derived from src, are left empty.

<!-- INCORRECT -->
<mds-url-view slot="window"></mds-url-view>

<!-- CORRECT -->
<mds-url-view slot="window" src="https://servizi.example.it/"></mds-url-view>

Do Not Use Outside mds-modal Without an Explicit Close Handler

<mds-url-view> auto-closes the nearest mds-modal ancestor on dismiss. Used outside a modal, the close button fires mdsUrlViewClose but nothing hides the component - you must listen for the event and handle visibility yourself.

<!-- INCORRECT - dismiss button fires but nothing hides the component -->
<mds-url-view src="https://servizi.example.it/" label="Portale"></mds-url-view>

<!-- CORRECT - listen and hide manually when used standalone -->
<div id="url-wrapper">
  <mds-url-view id="url-view" src="https://servizi.example.it/" label="Portale"></mds-url-view>
</div>
<script>
  document.querySelector('#url-view').addEventListener('mdsUrlViewClose', () => {
    document.querySelector('#url-wrapper').hidden = true;
  });
</script>

Do Not Pierce the Shadow DOM to Style Internals

The supported customization surface is the five --mds-url-view-* CSS custom properties. Targeting shadow internals via ::part() on undocumented parts, >>>, or class-name hacks couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-url-view >>> .header {
  background: navy;
}
mds-url-view >>> .iframe {
  border: 2px solid red;
}

/* CORRECT */
mds-url-view {
  --mds-url-view-background: rgb(var(--magma-accent-surface));
  --mds-url-view-color: rgb(var(--magma-accent-fg));
  --mds-url-view-header-shadow: var(--shadow-md-sharp);
}

Do Not Pass a Relative URL to src

The component calls new URL(src) to extract the hostname for the fallback title and ARIA labels. A relative path has no hostname, so the header and the ARIA labels show the raw path instead of the domain. Always pass an absolute URL.

<!-- INCORRECT -->
<mds-url-view slot="window" src="/portale/servizi"></mds-url-view>

<!-- CORRECT -->
<mds-url-view slot="window" src="https://servizi.example.it/portale"></mds-url-view>

Do Not Use loading="false" to Disable Lazy Loading

loading accepts the string values "lazy" and "eager", not booleans. loading="false" is outside the type and is passed to the iframe as is: it loads eagerly only because the browser treats any unknown value as eager. Write the value you mean.

<!-- INCORRECT -->
<mds-url-view slot="window" src="https://example.com/" loading="false"></mds-url-view>

<!-- CORRECT -->
<mds-url-view slot="window" src="https://example.com/" loading="eager"></mds-url-view>