Dialog

Dialog is a modal pop-up used to present the user with information requiring their immediate attention

import { Dialog } from "@roku-sdk/components";

Dialog(props: IDialogProps): JSX.Element

Description

Dialog is a modal pop-up used to present the user with information requiring their immediate attention. It supports a title, message, bullet text, graphic, and button regions. Dialogs intercept all key events except Home and are closed automatically by Back or Home.

Note: Consider using StandardDialog (Roku OS 10.0+) for new development, which
provides updated graphics and color palette support.

Parameters

Name	Type	Description
`props`	IDialogProps

Example

<Dialog
    title="Confirm Action"
    message="Are you sure you want to proceed?"
    iconUri="pkg:/images/dialog-icon.png"
    buttons={["OK", "Cancel"]}
    close={false}
    onButtonSelected={(index) => {
        if (index === 0) handleConfirm();
        else handleCancel();
    }}
    onWasClosed={() => console.log("Dialog closed")}
/>

Types

IDialogProps

Properties for the Dialog node.

The Dialog node defines a modal pop-up dialog used to present the user with information requiring their immediate attention. The dialog is configured to have up to five regions: title, message, bullet text, graphic, and buttons. All regions are optional except the title.

Dialogs are modal and intercept all key events except the Home key. They are closed automatically when the user presses the Home or Back key. If optionsDialog is true, pressing the Options key also closes the dialog.

Note: Roku OS 10.0 introduced the StandardDialog node with updated graphics and
color palette support. Consider using StandardDialog for new development.

Name	Type	Description
`backgroundUri?`	`Uri`	Specifies the bitmap to be displayed as the dialog background. Usually a 9-patch image to support dynamic resizing.
`bulletColor?`	`string`	Color of the bullet point text. See below.
`bulletFont?`	`string`	Font of the bullet point text. See below.
`bulletText?`	`string[]`	An array of strings to be displayed as a list of bullet points.
`buttons?`	`string[]`	Allows a set of buttons to be created by providing an array of button labels. Each string results in a Button node added to the dialog's internal ButtonGroup.
`close`	`boolean`	Causes the dialog to be dismissed. The dialog is dismissed whenever this field is set, regardless of whether it is set to true or false.
`dividerUri?`	`Uri`	Specifies a bitmap to be displayed as the divider between the title region and the remainder of the dialog. Usually a 9-patch image.
`focusButton?`	`number`	Causes the button with the specified index to receive focus when the dialog's ButtonGroup has the key focus.
`graphicHeight?`	`number`	Height of the bitmap graphic. If 0, the height from the image file is used. Must be set together with `graphicWidth` and before `graphicUri`.
`graphicUri?`	`Uri`	Specifies a bitmap to be displayed in the dialog. The bitmap is displayed below the bullet text region and above the buttons.
`graphicWidth?`	`number`	Width of the bitmap graphic. If 0, the width from the image file is used. Must be set together with `graphicHeight` and before `graphicUri`.
`iconUri?`	`Uri`	Specifies a bitmap to be displayed as a small icon next to the dialog title.
`maxHeight?`	`number`	Maximum height of the dialog. By default, the dialog scales height based on contents but never larger than display resolution. Setting smaller than contents enables a scrollable text region.
`message?`	`string`	The string to be displayed in the message region of the dialog. Newline and carriage return characters in the string result in the message being displayed as multiple lines.
`messageColor?`	`string`	Color of the message text.
`messageFont?`	`string`	Font of the message text.
`numberedBullets?`	`boolean`	When true, the bullet text will be displayed with numbers rather than bullets.
`onButtonFocused?`	`EventHandler<number>`	Fired when a button in the dialog receives the key focus. The handler receives the zero-based index of the focused button.
`onButtonSelected?`	`EventHandler<number>`	Fired when a button in the dialog is selected. The handler receives the zero-based index of the selected button.
`onWasClosed?`	`EventHandler<void>`	Fired when the dialog has been closed, whether by setting `close`, pressing Back/Home, pressing Options (if `optionsDialog` is true), or because another dialog was displayed.
`optionsDialog?`	`boolean`	When true, the dialog is automatically dismissed when the Options key is pressed.
`title?`	`string`	Title of the dialog box, displayed at the top alongside the icon.
`titleColor?`	`string`	Color of the title text.
`titleFont?`	`string`	Font of the title text.
`width?`	`number`	Width of the dialog. By default, this value is pulled from the system theme.

Extends IGroupProps.

IDialogProps.bulletColor

Color of the bullet point text.

Corresponds to the bulletTextColor field in the Roku reference.

IDialogProps.bulletFont

Font of the bullet point text.

Corresponds to the bulletTextFont field in the Roku reference.

Updated about 3 hours ago

What’s Next

DynamicKeyboard

Did this page help you?