Skip to content
nexus-dialogs
GitHub npm

Plugins and languages

A stable way to extend the library without touching its code: hooks that run with all dialogs (also those of form, wizard, confirmDelete…), custom field types for forms and texts in other languages.

#Install a plugin

A plugin is an object with a name and, if you want, install and hooks:

import { use, type Plugin } from 'nexus-dialogs'

const audit: Plugin = {
  name: 'audit',
  // Called once on install. Receives `configure` and `labels`.
  install: ({ configure }) => configure({ defaults: { dismissible: { backdrop: false } } }),
  // Before opening: return the changed options (or nothing, if you only observe).
  beforeOpen: (o) => ({ ...o, title: o.title ?? 'Notice' }),
  // With the dialog already on screen.
  afterOpen: (ctx, o) => console.log('opened', o.title, ctx.dialog),
  // After closing, with the result.
  afterClose: (r, o) => record({ title: o.title, confirmed: r.confirmed, reason: r.reason }),
}

use(audit) // true; with the same name again it does nothing and returns false
FunctionWhat it does
use(plugin)Installs the plugin. Returns false if there was already one with that name
unuse(name)Removes it. Returns false if it wasn't there
plugins()The names of the installed ones, in order

#How hooks behave

#Custom field types

With registerField (in nexus-dialogs/forms) a plugin adds a type that is used like any other in form() and wizard():

import { registerField } from 'nexus-dialogs/forms'

const remove = registerField('rating', (ctx, value) => {
  const el = document.createElement('input')
  el.id = ctx.id // the field's label points here
  el.type = 'number'
  el.min = '1'
  el.max = '5'
  el.value = String(value ?? 3)
  return {
    el,
    value: () => Number(el.value),
    focus: () => el.focus(),
    invalid: (on) => el.toggleAttribute('aria-invalid', on),
    validate: () => (Number(el.value) >= 1 ? null : 'Choose from 1 to 5.'),
    summary: () => `${el.value} of 5`, // what is shown in the wizard's review
  }
})

await form({ title: 'Rate', fields: [{ name: 'score', label: 'Score', type: 'rating' }] })
remove() // stops registering it

The control returns its el, value(), focus() and invalid(on); validate, summary, group (uses <fieldset> instead of <label>) and lazy are optional (the CustomControl type describes them). The label, the help text and the error message are provided by the library. An existing type cannot be replaced: registerField throws an error.

Since controls live inside the dialog's Shadow DOM, their CSS must go with them: a <style> inside el, or inline styles.

#Texts in other languages

Spanish and English are included. Other languages are registered with registerLanguage; whatever you don't translate is shown in English:

import { registerLanguage, configure, pageLanguage } from 'nexus-dialogs'
import { pt, fr } from 'nexus-dialogs/locales' // Portuguese (Brazil) and French, ready to use

registerLanguage('pt', pt)
configure({ lang: 'pt' }) // or configure({ lang: pageLanguage() }) to follow <html lang>

#What is promised

use, unuse, plugins, the shape of Plugin (name, install, beforeOpen, afterOpen, afterClose), registerField, CustomControl, registerLanguage and labelsFor are public API: changing them counts as a breaking change and npm run api:check watches it (Versioning and migrations).