Naming & API inconsistency: Modal vs Dialog

[aldahermaxim]

Hi!

I want to raise a discussion about the naming and API design differences between the web and native versions of what is essentially the same component.

The naming issue

On web, the component is called Modal. On native, it’s called Dialog. Both do the same thing — display an overlay that blocks interaction until dismissed.

From a UI/UX perspective, “Dialog” is a component type and “Modal” is a behavior, so a modal is really just a modal dialog.

The web version actually hints at this internally since it has Modal.Dialog as a sub-component, but then what is Modal itself if not the dialog?

Meanwhile, native just calls it Dialog which is cleaner and more accurate.

The API design differences

Beyond naming, the two APIs take quite different structural approaches:

// Web
<Modal>
  <Modal.Backdrop>
    <Modal.Container>
      <Modal.Dialog>
        <Modal.CloseTrigger />
        <Modal.Header>
          <Modal.Heading />
        </Modal.Header>
        <Modal.Body />
        <Modal.Footer />
      </Modal.Dialog>
    </Modal.Container>
  </Modal.Backdrop>
</Modal>

// Native
<Dialog>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Close />
      <Dialog.Title />
      <Dialog.Description />
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>

A few observations:

• On web, Modal.Backdrop wraps Modal.Container which wraps Modal.Dialog. But semantically, a backdrop sits behind the dialog — it doesn’t contain it. The native API gets this right with Dialog.Overlay and Dialog.Content as siblings.

• Native naming maps more naturally to accessibility roles — Dialog.Title and Dialog.Description align directly with aria-labelledby and aria-describedby.

• On the other hand, web provides useful layout structure with Modal.Header, Modal.Body, and Modal.Footer that native lacks.

Questions:

• Is there a reason behind the different naming and structure across platforms?

• Would aligning the naming and API shape be on the roadmap for consistency, especially for teams working cross-platform?

Not a bug, just a DX consistency concern. Would love to hear the team’s thinking on this.