Dialog

a dialog over the page that keeps focus until it closes.

usage

scenario

example

code

import { Dialog, Button } from 'charcell/react';

export function DialogExample() {
  return (
    <Dialog
      label="poyahoga gorge"
      role="alertdialog"
      trigger={({ triggerProps }) => (
        <Button {...triggerProps} label="jump the gorge" />
      )}
      actions={({ closeProps }) => (
        <>
          <Button {...closeProps} label="turn back" variant="dense" />
          <Button {...closeProps} label="jump the gorge" variant="dense" />
        </>
      )}
    >
      jumping the poyahoga gorge, although tempting, is highly illegal and
      dangerous.
    </Dialog>
  );
}

<script setup lang="ts">
import { Dialog, Button } from 'charcell/vue';
</script>

<template>
  <Dialog label="poyahoga gorge" role="alertdialog">
    jumping the poyahoga gorge, although tempting, is highly illegal and
    dangerous.
    <template #trigger="{ triggerProps }">
      <Button v-bind="triggerProps" label="jump the gorge" />
    </template>
    <template #actions="{ closeProps }">
      <Button v-bind="closeProps" label="turn back" variant="dense" /><Button
        v-bind="closeProps"
        label="jump the gorge"
        variant="dense"
      />
    </template>
  </Dialog>
</template>

<script lang="ts">
  import { Dialog, Button } from 'charcell/svelte';
</script>

<Dialog label="poyahoga gorge" role="alertdialog">
  jumping the poyahoga gorge, although tempting, is highly illegal and
  dangerous.
  {#snippet trigger({ triggerProps })}
    <Button {...triggerProps} label="jump the gorge" />
  {/snippet}
  {#snippet actions({ closeProps })}
    <Button {...closeProps} label="turn back" variant="dense" /><Button
      {...closeProps}
      label="jump the gorge"
      variant="dense"
    />
  {/snippet}
</Dialog>

<!-- component: DialogDriver (behavior not included) --><button
  class="CharcellButton CharcellButton--boxed CharcellButton--interactive"
  type="button"
>
  jump the gorge</button
><!-- /component -->

import { Dialog, Button } from 'charcell/react';

export function DialogExample() {
  return (
    <Dialog
      label="poyahoga gorge"
      role="alertdialog"
      border="none"
      trigger={({ triggerProps }) => (
        <Button {...triggerProps} label="jump the gorge" />
      )}
      actions={({ closeProps }) => (
        <>
          <Button {...closeProps} label="turn back" variant="dense" />
          <Button {...closeProps} label="jump the gorge" variant="dense" />
        </>
      )}
    >
      jumping the poyahoga gorge, although tempting, is highly illegal and
      dangerous.
    </Dialog>
  );
}

<script setup lang="ts">
import { Dialog, Button } from 'charcell/vue';
</script>

<template>
  <Dialog label="poyahoga gorge" role="alertdialog" border="none">
    jumping the poyahoga gorge, although tempting, is highly illegal and
    dangerous.
    <template #trigger="{ triggerProps }">
      <Button v-bind="triggerProps" label="jump the gorge" />
    </template>
    <template #actions="{ closeProps }">
      <Button v-bind="closeProps" label="turn back" variant="dense" /><Button
        v-bind="closeProps"
        label="jump the gorge"
        variant="dense"
      />
    </template>
  </Dialog>
</template>

<script lang="ts">
  import { Dialog, Button } from 'charcell/svelte';
</script>

<Dialog label="poyahoga gorge" role="alertdialog" border="none">
  jumping the poyahoga gorge, although tempting, is highly illegal and
  dangerous.
  {#snippet trigger({ triggerProps })}
    <Button {...triggerProps} label="jump the gorge" />
  {/snippet}
  {#snippet actions({ closeProps })}
    <Button {...closeProps} label="turn back" variant="dense" /><Button
      {...closeProps}
      label="jump the gorge"
      variant="dense"
    />
  {/snippet}
</Dialog>

<!-- component: DialogDriver (behavior not included) --><button
  class="CharcellButton CharcellButton--boxed CharcellButton--interactive"
  type="button"
>
  jump the gorge</button
><!-- /component -->

import { Dialog, Button } from 'charcell/react';

export function DialogExample() {
  return (
    <Dialog
      label="poyahoga gorge"
      role="alertdialog"
      border="single"
      trigger={({ triggerProps }) => (
        <Button {...triggerProps} label="jump the gorge" />
      )}
      actions={({ closeProps }) => (
        <>
          <Button {...closeProps} label="turn back" variant="dense" />
          <Button {...closeProps} label="jump the gorge" variant="dense" />
        </>
      )}
    >
      jumping the poyahoga gorge, although tempting, is highly illegal and
      dangerous.
    </Dialog>
  );
}

<script setup lang="ts">
import { Dialog, Button } from 'charcell/vue';
</script>

<template>
  <Dialog label="poyahoga gorge" role="alertdialog" border="single">
    jumping the poyahoga gorge, although tempting, is highly illegal and
    dangerous.
    <template #trigger="{ triggerProps }">
      <Button v-bind="triggerProps" label="jump the gorge" />
    </template>
    <template #actions="{ closeProps }">
      <Button v-bind="closeProps" label="turn back" variant="dense" /><Button
        v-bind="closeProps"
        label="jump the gorge"
        variant="dense"
      />
    </template>
  </Dialog>
</template>

<script lang="ts">
  import { Dialog, Button } from 'charcell/svelte';
</script>

<Dialog label="poyahoga gorge" role="alertdialog" border="single">
  jumping the poyahoga gorge, although tempting, is highly illegal and
  dangerous.
  {#snippet trigger({ triggerProps })}
    <Button {...triggerProps} label="jump the gorge" />
  {/snippet}
  {#snippet actions({ closeProps })}
    <Button {...closeProps} label="turn back" variant="dense" /><Button
      {...closeProps}
      label="jump the gorge"
      variant="dense"
    />
  {/snippet}
</Dialog>

<!-- component: DialogDriver (behavior not included) --><button
  class="CharcellButton CharcellButton--boxed CharcellButton--interactive"
  type="button"
>
  jump the gorge</button
><!-- /component -->

import { Dialog, Button } from 'charcell/react';

export function DialogExample() {
  return (
    <Dialog
      label="poyahoga gorge"
      role="alertdialog"
      border="rounded"
      trigger={({ triggerProps }) => (
        <Button {...triggerProps} label="jump the gorge" />
      )}
      actions={({ closeProps }) => (
        <>
          <Button {...closeProps} label="turn back" variant="dense" />
          <Button {...closeProps} label="jump the gorge" variant="dense" />
        </>
      )}
    >
      jumping the poyahoga gorge, although tempting, is highly illegal and
      dangerous.
    </Dialog>
  );
}

<script setup lang="ts">
import { Dialog, Button } from 'charcell/vue';
</script>

<template>
  <Dialog label="poyahoga gorge" role="alertdialog" border="rounded">
    jumping the poyahoga gorge, although tempting, is highly illegal and
    dangerous.
    <template #trigger="{ triggerProps }">
      <Button v-bind="triggerProps" label="jump the gorge" />
    </template>
    <template #actions="{ closeProps }">
      <Button v-bind="closeProps" label="turn back" variant="dense" /><Button
        v-bind="closeProps"
        label="jump the gorge"
        variant="dense"
      />
    </template>
  </Dialog>
</template>

<script lang="ts">
  import { Dialog, Button } from 'charcell/svelte';
</script>

<Dialog label="poyahoga gorge" role="alertdialog" border="rounded">
  jumping the poyahoga gorge, although tempting, is highly illegal and
  dangerous.
  {#snippet trigger({ triggerProps })}
    <Button {...triggerProps} label="jump the gorge" />
  {/snippet}
  {#snippet actions({ closeProps })}
    <Button {...closeProps} label="turn back" variant="dense" /><Button
      {...closeProps}
      label="jump the gorge"
      variant="dense"
    />
  {/snippet}
</Dialog>

<!-- component: DialogDriver (behavior not included) --><button
  class="CharcellButton CharcellButton--boxed CharcellButton--interactive"
  type="button"
>
  jump the gorge</button
><!-- /component -->

import { Dialog, Button } from 'charcell/react';

export function DialogExample() {
  return (
    <Dialog
      label="poyahoga gorge"
      role="alertdialog"
      border="heavy"
      trigger={({ triggerProps }) => (
        <Button {...triggerProps} label="jump the gorge" />
      )}
      actions={({ closeProps }) => (
        <>
          <Button {...closeProps} label="turn back" variant="dense" />
          <Button {...closeProps} label="jump the gorge" variant="dense" />
        </>
      )}
    >
      jumping the poyahoga gorge, although tempting, is highly illegal and
      dangerous.
    </Dialog>
  );
}

<script setup lang="ts">
import { Dialog, Button } from 'charcell/vue';
</script>

<template>
  <Dialog label="poyahoga gorge" role="alertdialog" border="heavy">
    jumping the poyahoga gorge, although tempting, is highly illegal and
    dangerous.
    <template #trigger="{ triggerProps }">
      <Button v-bind="triggerProps" label="jump the gorge" />
    </template>
    <template #actions="{ closeProps }">
      <Button v-bind="closeProps" label="turn back" variant="dense" /><Button
        v-bind="closeProps"
        label="jump the gorge"
        variant="dense"
      />
    </template>
  </Dialog>
</template>

<script lang="ts">
  import { Dialog, Button } from 'charcell/svelte';
</script>

<Dialog label="poyahoga gorge" role="alertdialog" border="heavy">
  jumping the poyahoga gorge, although tempting, is highly illegal and
  dangerous.
  {#snippet trigger({ triggerProps })}
    <Button {...triggerProps} label="jump the gorge" />
  {/snippet}
  {#snippet actions({ closeProps })}
    <Button {...closeProps} label="turn back" variant="dense" /><Button
      {...closeProps}
      label="jump the gorge"
      variant="dense"
    />
  {/snippet}
</Dialog>

<!-- component: DialogDriver (behavior not included) --><button
  class="CharcellButton CharcellButton--boxed CharcellButton--interactive"
  type="button"
>
  jump the gorge</button
><!-- /component -->

import { Dialog, Button } from 'charcell/react';

export function DialogExample() {
  return (
    <Dialog
      label="poyahoga gorge"
      role="alertdialog"
      border="double"
      trigger={({ triggerProps }) => (
        <Button {...triggerProps} label="jump the gorge" />
      )}
      actions={({ closeProps }) => (
        <>
          <Button {...closeProps} label="turn back" variant="dense" />
          <Button {...closeProps} label="jump the gorge" variant="dense" />
        </>
      )}
    >
      jumping the poyahoga gorge, although tempting, is highly illegal and
      dangerous.
    </Dialog>
  );
}

<script setup lang="ts">
import { Dialog, Button } from 'charcell/vue';
</script>

<template>
  <Dialog label="poyahoga gorge" role="alertdialog" border="double">
    jumping the poyahoga gorge, although tempting, is highly illegal and
    dangerous.
    <template #trigger="{ triggerProps }">
      <Button v-bind="triggerProps" label="jump the gorge" />
    </template>
    <template #actions="{ closeProps }">
      <Button v-bind="closeProps" label="turn back" variant="dense" /><Button
        v-bind="closeProps"
        label="jump the gorge"
        variant="dense"
      />
    </template>
  </Dialog>
</template>

<script lang="ts">
  import { Dialog, Button } from 'charcell/svelte';
</script>

<Dialog label="poyahoga gorge" role="alertdialog" border="double">
  jumping the poyahoga gorge, although tempting, is highly illegal and
  dangerous.
  {#snippet trigger({ triggerProps })}
    <Button {...triggerProps} label="jump the gorge" />
  {/snippet}
  {#snippet actions({ closeProps })}
    <Button {...closeProps} label="turn back" variant="dense" /><Button
      {...closeProps}
      label="jump the gorge"
      variant="dense"
    />
  {/snippet}
</Dialog>

<!-- component: DialogDriver (behavior not included) --><button
  class="CharcellButton CharcellButton--boxed CharcellButton--interactive"
  type="button"
>
  jump the gorge</button
><!-- /component -->

as text

at rest

┌─ poyahoga gorge ─────────────────╖
│ jumping the poyahoga gorge,      ║
│ although tempting, is highly     ║
│ illegal and dangerous.           ║
│      turn back   jump the gorge  ║
╘══════════════════════════════════╝

hover

┌─ poyahoga gorge ─────────────────╖
│ jumping the poyahoga gorge,      ║
│ although tempting, is highly     ║
│ illegal and dangerous.           ║
│      turn back   jump the gorge  ║
╘══════════════════════════════════╝

press

┌─ poyahoga gorge ─────────────────╖
│ jumping the poyahoga gorge,      ║
│ although tempting, is highly     ║
│ illegal and dangerous.           ║
│      turn back   jump the gorge  ║
╘══════════════════════════════════╝

focus

┌─ poyahoga gorge ─────────────────╖
│ jumping the poyahoga gorge,      ║
│ although tempting, is highly     ║
│ illegal and dangerous.           ║
│     ❯turn back   jump the gorge  ║
╘══════════════════════════════════╝

props

Dialog

direction'ltr' | 'rtl': The reading direction its keys and placement follow ('rtl' mirrors the arrow keys); the page's, once mounted, when unset.
finalFocus() => HTMLElement | null: Where focus goes as the dialog closes when neither its trigger nor what opened it is on the page any more (a menu in the row the dialog just deleted): focus would otherwise fall to the page itself.
labelstring: The window's title and the dialog's accessible name.
initialFocus() => HTMLElement | null: Where focus goes as the dialog opens, in place of its first focusable element: the safe choice in a dialog that asks before something destructive.
describedBystring: The id of an element that describes the dialog, for its aria-describedby.
preventScrollboolean= true: Lock the page's scroll while the dialog is open.
widthnumber: The window's width in whole cells, its ring included; it fits its content when unset.
minWidthnumber: The window's least width in whole cells, its ring included: it grows past it with its content.
openboolean: Controlled open state; pair it with onOpenChange.; binds with v-model:open in vue, bind:open in svelte
defaultOpenboolean: Uncontrolled initial open state.
onOpenChange(open: boolean) => void: Called with the next open state whenever the dialog opens or closes.
modalboolean= true: Trap focus and hide the page from assistive technology.
closeOnEscapeboolean= true: Whether escape closes the dialog.
closeOnInteractOutsideboolean= true: Whether a click outside the window closes it.
role'dialog' | 'alertdialog': The dialog's role: 'alertdialog' for a dialog that interrupts to ask something.
border'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of every side of the window's ring: single, rounded, heavy, double or none.
borderX'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's start and end sides, over border.
borderY'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's top and bottom sides, over border.
borderTop'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's top side, over borderY and border.
borderEnd'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's end side, over borderX and border; double when none of them is set, raising the window.
borderBottom'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's bottom side, over borderY and border; double when none of them is set, raising the window.
borderStart'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's start side, over borderX and border.

DialogPanel

labelstring: The window's title, straddling the top of its ring.
widthnumber: The window's width in whole cells, its ring included; it fits its content when unset, and never outgrows the space it has.
minWidthnumber: The window's least width in whole cells, its ring included: it grows past it with its content.
border'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of every side of the window's ring: single, rounded, heavy, double or none.
borderX'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's start and end sides, over border.
borderY'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's top and bottom sides, over border.
borderTop'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's top side, over borderY and border.
borderEnd'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's end side, over borderX and border.
borderBottom'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's bottom side, over borderY and border.
borderStart'none' | 'single' | 'rounded' | 'heavy' | 'double': The style of the window's ring's start side, over borderX and border.
contentPropsobject: Spread onto the window (Zag's getContentProps()).

it also takes any other attribute of its <div>.

slots

in react, the default slot is children and each named slot a prop of its name, a function where the slot hands values; in vue, a slot; in svelte, a snippet.

Dialog

trigger{ triggerProps: Record<string, unknown> }its values required: What opens the dialog, typically a Button: spread triggerProps onto it.
default: The window's content.
actions{ closeProps: Record<string, unknown> }: The window's last row, its buttons. Spread closeProps onto one to close the dialog.

DialogPanel

default
actions