Dialogic: manage dialogs and notifications

• Supported JavaScript libraries
• Features
• Demo
• Usage
• API
  • Dialog and Notification component
    • Options
  • show
  • hide
  • dialogic options
    • component
    • className
    • styles
    • timeout
    • queued
    • toggle
    • willShow
    • didShow
    • willHide
    • didHide
    • Component options
  • hideAll
  • resetAll
  • Handling multiple items with identity options
    • Simultaneous, at the same location
    • Simultaneous, at different locations
    • Sequence of items
  • exists
  • getCount
  • Timer functions
    • pause
    • resume
    • isPaused
    • getRemaining
    • useRemaining
  • Automatically responding to a variable state, such as a route
  • useDialog
    • Options
    • Calling show and hide directly
• Shout out
• License

Supported JavaScript libraries

• React and NextJS - Dialogic for React documentation
• Mithril - Dialogic for Mithril documentation
• Svelte and SvelteKit - Dialogic for Svelte documentation

For a more basic solution in vanilla JS, check out dialogic-js.

Features

item: a dialog/modal or a notification

• Manage multiple items
  • Manage simultaneous (stacked) items
  • Manage a queue of items to show sequentially
• Optional automatic mode
  • Show and hide when matching a condition such as a route
• Transitions
  • Show and hide an item with specific transition options (or use CSS)
  • Handle separate spawn locations (for example for different types of notifications)
  • Replace an already displayed item
  • Hide all items, or only ones matching a specific id or spawn
  • Remove all items, or only ones matching a specific id or spawn
• Timer
  • Automatic timeout to hide items after a given time
  • Pause, resume and stop a timer
• State
  • Get the number of displayed items (all, per id or per spawn)
  • Get the paused state of a displayed item using a timer
  • Get the remaining time of a displayed item using a timer
  • Use a callback function when an item is shown or hidden
  • Use the returned Promise when an item is shown or hidden
• Styling
  • Use custom CSS classes or style options
  • Manage timings with CSS (or use transition options)
  • Use any UI library
• Written in TypeScript

Dialogic does not provide any styling for dialogs or notifications. This gives you the freedom to plug into your own codebase or use any other UI library.

Demo

Demo page

Usage

To create a dialog or notification, you need:

• Functions show and hide
• A Dialog / Notification component

The usage of the component varies somewhat per JS library - see library specific notes:

• Dialogic for React
• Dialogic for Mithril
• Dialogic for Svelte and SvelteKit

API

Dialog and Notification component

Location where the dialog or notification (after this: "item") will be drawn.

With Mithril:

m(Dialog)
m(Dialog, { spawn: "settings" })

With React:

<Dialog />
<Dialog spawn="settings" />

With Svelte:

<Dialog />
<Dialog spawn="settings" />

Options

| Name | Type | Required | Description | Default value | |----------|----------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------| | spawn | string | No | Spawn identifier, useful when using multiple spawn locations. See Handling multiple items with identity options | "default_spawn" |

show

Shows an item.

dialog.show({
  dialogic: {
    component: DialogView,
    className: "dialog",
  },
  title: "Dialog Title"
})

• When queued is true (which is the default for notifications), any further call to show will queue the item and it will be displayed when the current item has transitioned to hidden.
• When an instance already exists, show replaces the content.

Signature

show: <T>(options: Options<T>, componentOptions?: T) => Promise<Item<T>>;

type Dialogic.Options<T> = {
  dialogic?: DialogicOptions<T>;
} & T;

hide

Hides an item.

dialog.hide()

When identity options are used, only hides the item that match the identity options:

dialog.hide({
  dialogic: {
    id: "settings", // example: use id and/or spawn
  }
})

Signature

hide: <T>(options?: Options<T>, componentOptions?: T) => Promise<Item<T>>;

type Dialogic.Options<T> = {
  dialogic?: DialogicOptions<T>;
} & T;

dialogic options

Options passed to show, hide and hideAll. The options are further explained below.

| Name | Type | Required | Description | Default value | |-----------------------|------------------------------------------------------------------------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| | component | Function component | No | The component to render as an item. | | | className | string | No | Class added to the wrapper around component; also the base name for transition classes (more below). | | | styles | TransitionStyles object or (domElement: HTMLElement) => TransitionStyles | No | Pass transition styles in JS. | | | timeout | number (ms) | No | Creates a timer. When the dialog is completely shown the timer is started automatically. After timeout the dialog is hidden. Use 0 to prevent the timer from running. | For notifications 3000 | | queued | boolean | No | Set to true to manage multiple dialogs in time (more useful for notifications). | false; for notifications true | | toggle | boolean | No | Set to true to make show() switch between shown and hidden state. | false | | willShow | (item: Dialogic.Item) => void | No | Function called just before the item will be shown (before transitioning). | | | didShow | (item: Dialogic.Item) => void | No | Function called when the item is completely shown (after transitioning). | | | willHide | (item: Dialogic.Item) => void | No | Function called just before the item will be hidden (before transitioning). | | | didHide | (item: Dialogic.Item) => void | No | Function called when the item is completely hidden (after transitioning). |