Prompt Dialog

Used to interrupt the user with a mandatory validation or action.

• View on Github

• View Core API

• View on Figma

Import

import { PromptProvider, usePrompt } from '@pluralsight/react'

Anatomy

1. Dialog Container
2. Header (optional)
3. Heading (optional)
4. Body
5. Label (hidden or visible)
6. Input
7. Footer
8. Cancel Button
9. Confirm Button

Usage

Non-destructive

Use a non-destructive Prompt Dialog when you need a validation that does not result in a destructive behavior.

(required)

import { Button, PromptProvider, usePrompt } from '@pluralsight/react'
import Container from '../Container/Container.js'

function PromptFeature() {
  const { prompt } = usePrompt()
  const CONFIRM_KEY = 'CONFIRM'

  async function handleOnClick() {
    try {
      const validation = await prompt({
        heading: 'Validation required.',
        text: 'This action requires additional validation.',
        promptValidationKey: CONFIRM_KEY,
      })

      if (validation === CONFIRM_KEY) {
        // do something
      }
    } catch (error) {
      // handle error
    }
  }

  return <Button onClick={handleOnClick}>Update role</Button>
}

export default function PromptDialog() {
  return (
    <Container>
      <PromptProvider>
        <PromptFeature />
      </PromptProvider>
    </Container>
  )
}

Destructive

When you need a confirmation from a user that will result in a destructive action, just add the kind option with a value of destructive to the prompt function.

(required)

import { Button, PromptProvider, usePrompt } from '@pluralsight/react'
import Container from '../Container/Container.js'

function PromptFeature() {
  const { prompt } = usePrompt()
  const CONFIRM_KEY = 'DELETE'

  async function handleOnClick() {
    try {
      const validation = await prompt({
        heading: 'Delete Channel',
        kind: 'destructive',
        text: 'Are you sure you want to delete this channel? This action cannot be undone.',
        promptValidationKey: CONFIRM_KEY,
      })

      if (validation === CONFIRM_KEY) {
        // do something
      }
    } catch (error) {
      // handle error
    }
  }

  return (
    <Button sentiment="danger" onClick={handleOnClick}>
      Delete channel
    </Button>
  )
}

export default function PromptDialog() {
  return (
    <Container>
      <PromptProvider>
        <PromptFeature />
      </PromptProvider>
    </Container>
  )
}

Customizing

You can customize the Prompt Dialog in the following ways:

1. Unused Classes

Each component layer of the Prompt has a unused class name that can be utilized in your local CSS to customize the Prompt at any level.

1. pando-alert: The element of the Prompt Alert.
2. pando-alert-header: The header element of the Alert.
3. pando-alert-icon: The heading icon element of the Alert.
4. pando-alert-heading: The heading element of the Alert.
5. pando-alert-body: The content element of the Alert.
6. pando-alert-label: The label element of the Alert.
7. pando-alert-input: The input element of the Alert.
8. pando-alert-footer: The footer element of the Alert.
9. pando-alert-cancel: The cancel button element of the Alert.
10. pando-alert-confirm: The confirm button element of the Alert.

3. Ejected Prompt Dialog

For a low-level "ejected" approach, you can use the Headless-styles API to customize the Prompt Alert however you prefer while keeping the accessibility behavior.

import {
  getAlertDialogProps,
  getAlertDialogHeaderProps,
  getAlertDialogHeadingProps,
  getAlertDialogBodyProps,
  getAlertDialogFooterProps,
} from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Prompt Dialogs are to be used to interrupt the user's task with important, critical, or warning information. This is the Pluralsight themed version of a browser's native window.prompt() function.

Patterns

Do use the Prompt Dialog when you need the user to validate a decision.

Don't use the Modal when you need the user to validate a decision.

Do keep Prompt Dialog layout unaltered.

Don't manipulate or add any additional elements/styles to the Prompt Dialog.

Usage

Do use sparingly in a user experience.

Don't abuse the use of this Dialog by using multiple times within a page.

API

PromptProvider

The PromptProvider should NOT be used at the top level of your application. It should be used at the top level of the feature that needs a Prompt Dialog for better performance.

Paramters

usePrompt

The hook returns a string value of either "cancel" or the promptValidationKey value.

interface ContextProps {
  prompt: (options: PromptDialogProps) => Promise<string>
}

function usePrompt(): ContextProps

Parameters

interface PromptDialogProps {
  bodyId?: string
  headingId?: string
  heading?: string
  kind?: 'non-destructive' | 'destructive'
  promptValidationKey?: string
  text: string
}

1. bodyId: The id of the content element of the Prompt Dialog. A default id will be generated if not provided.
2. headingId: The id of the heading element of the Prompt Dialog. A default id will be generated if not provided.
3. heading: The text of the heading element of the Prompt Dialog.
4. kind: The kind of Prompt Dialog. The value can be either non-destructive or destructive.
5. promptValidationKey: The value that will determine the form invalid state and returned on successful submission.
6. text: The text of the content element of the Prompt Dialog.

Accessibility

The Pando Prompt Dialog is fully accessible and screen-readable through the following features:

1. The Prompt Dialog uses the dialog element for native browser a11y support.
2. The dialog element uses the role of alertdialog to indicate to screen readers that the dialog contains important information.
3. The dialog element uses the aria-modal attribute to indicate to screen readers that the dialog is modal.
4. The dialog element uses the aria-labelledby attribute to indicate to screen readers that the dialog has a heading.
5. The dialog element uses the aria-describedby attribute to indicate to screen readers that the dialog has a content body.
6. The Dialog API automatically focuses back on the trigger when the Dialog is closed.
7. The Dialog traps focus within the Dialog when it is open.