Skip to content

refactor(dialog): MD3 updates, updated Dialog API #5072

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kachmashk wants to merge 5 commits into
base: main
Choose a base branch
from
Open

refactor(dialog): MD3 updates, updated Dialog API #5072

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d5b1361
refactor: updated Dialog to comply with Material3 guidelines
kachmashk Aug 20, 2026
49442ef
refactor: introduced new Dialog API, updated docs
kachmashk Aug 25, 2026
ab72a9c
refactor: added new test cases for new Dialog API
kachmashk Aug 25, 2026
4b92272
refactor: updated Examples, duplicated dialogs using new Dialog API
kachmashk Aug 25, 2026
bc47bf4
docs: updated docs for Dialog compound components
kachmashk Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 48 additions & 11 deletions docs/6.x/docs/components/Dialog/Dialog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,19 @@ import ExtendedExample from '@docs/components/ExtendedExample.tsx';
Dialogs inform users about a specific task and may contain critical information, require decisions, or involve multiple tasks.
To render the `Dialog` above other components, you'll need to wrap it with the [`Portal`](../Portal/Portal) component.

## Recommended props

| Prop | Type | Description |
| --- | --- | --- |
| `icon` | `IconSource` | Icon rendered through `Dialog.Icon`. |
| `title` | `ReactNode` | Dialog title rendered through `Dialog.Title`. |
| `content` | `ReactNode` | Required dialog content. Non-empty strings use Material 3 supporting-text styles. |
| `actions` | `DialogActionsProps[]` | Action labels, press handlers, and Button props. |
| `scrollable` | `boolean` | Renders content through `Dialog.ScrollArea` and a `ScrollView`. |
| `contentProps` | `DialogContentProps` | Props forwarded to `Dialog.Content`. |
| `scrollAreaProps` | `DialogScrollAreaProps` | Props forwarded to `Dialog.ScrollArea`. |
| `scrollViewProps` | `ScrollViewProps` | Props forwarded to `ScrollView`. |




Expand All @@ -21,7 +34,7 @@ To render the `Dialog` above other components, you'll need to wrap it with the [
```js
import * as React from 'react';
import { View } from 'react-native';
import { Button, Dialog, Portal, PaperProvider, Text } from 'react-native-paper';
import { Button, Dialog, Portal, PaperProvider } from 'react-native-paper';

const MyComponent = () => {
const [visible, setVisible] = React.useState(false);
Expand All @@ -35,15 +48,13 @@ const MyComponent = () => {
<View>
<Button onPress={showDialog}>Show Dialog</Button>
<Portal>
<Dialog visible={visible} onDismiss={hideDialog}>
<Dialog.Title>Alert</Dialog.Title>
<Dialog.Content>
<Text variant="bodyMedium">This is simple dialog</Text>
</Dialog.Content>
<Dialog.Actions>
<Button onPress={hideDialog}>Done</Button>
</Dialog.Actions>
</Dialog>
<Dialog
visible={visible}
onDismiss={hideDialog}
title="Alert"
content="This is simple dialog"
actions={[{ label: 'Done', onPress: hideDialog }]}
/>
</Portal>
</View>
</PaperProvider>
Expand All @@ -53,6 +64,32 @@ const MyComponent = () => {
export default MyComponent;
```

## Compound composition

`Dialog.Icon`, `Dialog.Title`, `Dialog.Content`, `Dialog.ScrollArea`, and
`Dialog.Actions` remain available for custom composition within `Dialog`.
Passing them through `children` is deprecated; prefer the props above.

## Migrating from children

```js
// Before
<Dialog visible={visible} onDismiss={hideDialog}>
<Dialog.Title>Alert</Dialog.Title>
<Dialog.Content><Text>Something happened.</Text></Dialog.Content>
<Dialog.Actions><Button onPress={hideDialog}>Done</Button></Dialog.Actions>
</Dialog>

// After
<Dialog
visible={visible}
onDismiss={hideDialog}
title="Alert"
content="Something happened."
actions={[{ label: 'Done', onPress: hideDialog }]}
/>
```


## Props
<span />
Expand Down Expand Up @@ -93,7 +130,7 @@ export default MyComponent;

<div>

### children (required)
### children (depracated, use props instead)

</div>

Expand Down
9 changes: 1 addition & 8 deletions docs/6.x/docs/components/Dialog/DialogIcon.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@ A component to show an icon in a Dialog.
## Usage
```js
import * as React from 'react';
import { StyleSheet } from 'react-native';
import { Dialog, Portal, Text } from 'react-native-paper';

const MyComponent = () => {
Expand All @@ -32,7 +31,7 @@ const MyComponent = () => {
<Portal>
<Dialog visible={visible} onDismiss={hideDialog}>
<Dialog.Icon icon="alert" />
<Dialog.Title style={styles.title}>This is a title</Dialog.Title>
<Dialog.Title>This is a title</Dialog.Title>
<Dialog.Content>
<Text variant="bodyMedium">This is simple dialog</Text>
</Dialog.Content>
Expand All @@ -41,12 +40,6 @@ const MyComponent = () => {
);
};

const styles = StyleSheet.create({
title: {
textAlign: 'center',
},
})

export default MyComponent;
```

Expand Down
8 changes: 4 additions & 4 deletions docs/src/data/componentDocs6x.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5206,10 +5206,10 @@
"Dialog/Dialog": {

@JKobrynski JKobrynski Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Run yarn docs generate - componentDocs6x.json and the .mdx pages are generated, and the JSDoc you added to DialogActions, DialogContent, DialogScrollArea and DialogTitle hasn't reached either. The hand-typed ### children (depracated…) heading will be overwritten.

"filepath": "Dialog/Dialog.tsx",
"title": "Dialog",
"description": "Dialogs inform users about a specific task and may contain critical information, require decisions, or involve multiple tasks.\nTo render the `Dialog` above other components, you'll need to wrap it with the [`Portal`](../Portal) component.\n\n## Usage\n```js\nimport * as React from 'react';\nimport { View } from 'react-native';\nimport { Button, Dialog, Portal, PaperProvider, Text } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const showDialog = () => setVisible(true);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <PaperProvider>\n <View>\n <Button onPress={showDialog}>Show Dialog</Button>\n <Portal>\n <Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Title>Alert</Dialog.Title>\n <Dialog.Content>\n <Text variant=\"bodyMedium\">This is simple dialog</Text>\n </Dialog.Content>\n <Dialog.Actions>\n <Button onPress={hideDialog}>Done</Button>\n </Dialog.Actions>\n </Dialog>\n </Portal>\n </View>\n </PaperProvider>\n );\n};\n\nexport default MyComponent;\n```",
"description": "Dialogs inform users about a specific task and may contain critical information, require decisions, or involve multiple tasks.\nTo render the `Dialog` above other components, you'll need to wrap it with the [`Portal`](../Portal) component.\n\n## Recommended props\n\n| Prop | Type | Description |\n| --- | --- | --- |\n| `icon` | `IconSource` | Icon rendered through `Dialog.Icon`. |\n| `title` | `ReactNode` | Dialog title rendered through `Dialog.Title`. |\n| `content` | `ReactNode` | Required dialog content. Non-empty strings use Material 3 supporting-text styles. |\n| `actions` | `DialogActionsProps[]` | Action labels, press handlers, and optional Button props. |\n| `scrollable` | `boolean` | Renders content through `Dialog.ScrollArea` and a `ScrollView`. |\n| `contentProps` | `DialogContentProps` | Props forwarded to `Dialog.Content`. |\n| `scrollAreaProps` | `DialogScrollAreaProps` | Props forwarded to `Dialog.ScrollArea`. |\n| `scrollViewProps` | `ScrollViewProps` | Props forwarded to `ScrollView`. |\n\n## Usage\n```js\nimport * as React from 'react';\nimport { View } from 'react-native';\nimport { Button, Dialog, Portal, PaperProvider } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const showDialog = () => setVisible(true);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <PaperProvider>\n <View>\n <Button onPress={showDialog}>Show Dialog</Button>\n <Portal>\n <Dialog\n visible={visible}\n onDismiss={hideDialog}\n title=\"Alert\"\n content=\"This is simple dialog\"\n actions={[{ label: 'Done', onPress: hideDialog }]}\n />\n </Portal>\n </View>\n </PaperProvider>\n );\n};\n\nexport default MyComponent;\n```\n\n## Compound composition\n\n`Dialog.Icon`, `Dialog.Title`, `Dialog.Content`, `Dialog.ScrollArea`, and\n`Dialog.Actions` remain available for custom composition within `Dialog`.\nPassing them through `children` is deprecated; prefer the props above.\n\n## Migrating from children\n\n```js\n// Before\n<Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Title>Alert</Dialog.Title>\n <Dialog.Content><Text>Something happened.</Text></Dialog.Content>\n <Dialog.Actions><Button onPress={hideDialog}>Done</Button></Dialog.Actions>\n</Dialog>\n\n// After\n<Dialog\n visible={visible}\n onDismiss={hideDialog}\n title=\"Alert\"\n content=\"Something happened.\"\n actions={[{ label: 'Done', onPress: hideDialog }]}\n/>\n```",
"link": "dialog",
"data": {
"description": "Dialogs inform users about a specific task and may contain critical information, require decisions, or involve multiple tasks.\nTo render the `Dialog` above other components, you'll need to wrap it with the [`Portal`](../Portal) component.\n\n## Usage\n```js\nimport * as React from 'react';\nimport { View } from 'react-native';\nimport { Button, Dialog, Portal, PaperProvider, Text } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const showDialog = () => setVisible(true);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <PaperProvider>\n <View>\n <Button onPress={showDialog}>Show Dialog</Button>\n <Portal>\n <Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Title>Alert</Dialog.Title>\n <Dialog.Content>\n <Text variant=\"bodyMedium\">This is simple dialog</Text>\n </Dialog.Content>\n <Dialog.Actions>\n <Button onPress={hideDialog}>Done</Button>\n </Dialog.Actions>\n </Dialog>\n </Portal>\n </View>\n </PaperProvider>\n );\n};\n\nexport default MyComponent;\n```",
"description": "Dialogs inform users about a specific task and may contain critical information, require decisions, or involve multiple tasks.\nTo render the `Dialog` above other components, you'll need to wrap it with the [`Portal`](../Portal) component.\n\n## Recommended props\n\n| Prop | Type | Description |\n| --- | --- | --- |\n| `icon` | `IconSource` | Icon rendered through `Dialog.Icon`. |\n| `title` | `ReactNode` | Dialog title rendered through `Dialog.Title`. |\n| `content` | `ReactNode` | Required dialog content. Non-empty strings use Material 3 supporting-text styles. |\n| `actions` | `DialogActionsProps[]` | Action labels, press handlers, and optional Button props. |\n| `scrollable` | `boolean` | Renders content through `Dialog.ScrollArea` and a `ScrollView`. |\n| `contentProps` | `DialogContentProps` | Props forwarded to `Dialog.Content`. |\n| `scrollAreaProps` | `DialogScrollAreaProps` | Props forwarded to `Dialog.ScrollArea`. |\n| `scrollViewProps` | `ScrollViewProps` | Props forwarded to `ScrollView`. |\n\n## Usage\n```js\nimport * as React from 'react';\nimport { View } from 'react-native';\nimport { Button, Dialog, Portal, PaperProvider } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const showDialog = () => setVisible(true);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <PaperProvider>\n <View>\n <Button onPress={showDialog}>Show Dialog</Button>\n <Portal>\n <Dialog\n visible={visible}\n onDismiss={hideDialog}\n title=\"Alert\"\n content=\"This is simple dialog\"\n actions={[{ label: 'Done', onPress: hideDialog }]}\n />\n </Portal>\n </View>\n </PaperProvider>\n );\n};\n\nexport default MyComponent;\n```\n\n## Compound composition\n\n`Dialog.Icon`, `Dialog.Title`, `Dialog.Content`, `Dialog.ScrollArea`, and\n`Dialog.Actions` remain available for custom composition within `Dialog`.\nPassing them through `children` is deprecated; prefer the props above.\n\n## Migrating from children\n\n```js\n// Before\n<Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Title>Alert</Dialog.Title>\n <Dialog.Content><Text>Something happened.</Text></Dialog.Content>\n <Dialog.Actions><Button onPress={hideDialog}>Done</Button></Dialog.Actions>\n</Dialog>\n\n// After\n<Dialog\n visible={visible}\n onDismiss={hideDialog}\n title=\"Alert\"\n content=\"Something happened.\"\n actions={[{ label: 'Done', onPress: hideDialog }]}\n/>\n```",
"displayName": "Dialog",
"methods": [],
"statics": [],
Expand Down Expand Up @@ -5400,10 +5400,10 @@
"Dialog/DialogIcon": {
"filepath": "Dialog/DialogIcon.tsx",
"title": "Dialog.Icon",
"description": "@supported Available in v5.x with theme version 3\nA component to show an icon in a Dialog.\n\n## Usage\n```js\nimport * as React from 'react';\nimport { StyleSheet } from 'react-native';\nimport { Dialog, Portal, Text } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <Portal>\n <Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Icon icon=\"alert\" />\n <Dialog.Title style={styles.title}>This is a title</Dialog.Title>\n <Dialog.Content>\n <Text variant=\"bodyMedium\">This is simple dialog</Text>\n </Dialog.Content>\n </Dialog>\n </Portal>\n );\n};\n\nconst styles = StyleSheet.create({\n title: {\n textAlign: 'center',\n },\n})\n\nexport default MyComponent;\n```",
"description": "@supported Available in v5.x with theme version 3\nA component to show an icon in a Dialog.\n\n## Usage\n```js\nimport * as React from 'react';\nimport { Dialog, Portal, Text } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <Portal>\n <Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Icon icon=\"alert\" />\n <Dialog.Title>This is a title</Dialog.Title>\n <Dialog.Content>\n <Text variant=\"bodyMedium\">This is simple dialog</Text>\n </Dialog.Content>\n </Dialog>\n </Portal>\n );\n};\n\nexport default MyComponent;\n```",
"link": "dialog-icon",
"data": {
"description": "@supported Available in v5.x with theme version 3\nA component to show an icon in a Dialog.\n\n## Usage\n```js\nimport * as React from 'react';\nimport { StyleSheet } from 'react-native';\nimport { Dialog, Portal, Text } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <Portal>\n <Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Icon icon=\"alert\" />\n <Dialog.Title style={styles.title}>This is a title</Dialog.Title>\n <Dialog.Content>\n <Text variant=\"bodyMedium\">This is simple dialog</Text>\n </Dialog.Content>\n </Dialog>\n </Portal>\n );\n};\n\nconst styles = StyleSheet.create({\n title: {\n textAlign: 'center',\n },\n})\n\nexport default MyComponent;\n```",
"description": "@supported Available in v5.x with theme version 3\nA component to show an icon in a Dialog.\n\n## Usage\n```js\nimport * as React from 'react';\nimport { Dialog, Portal, Text } from 'react-native-paper';\n\nconst MyComponent = () => {\n const [visible, setVisible] = React.useState(false);\n\n const hideDialog = () => setVisible(false);\n\n return (\n <Portal>\n <Dialog visible={visible} onDismiss={hideDialog}>\n <Dialog.Icon icon=\"alert\" />\n <Dialog.Title>This is a title</Dialog.Title>\n <Dialog.Content>\n <Text variant=\"bodyMedium\">This is simple dialog</Text>\n </Dialog.Content>\n </Dialog>\n </Portal>\n );\n};\n\nexport default MyComponent;\n```",
"displayName": "Dialog.Icon",
"methods": [],
"statics": [],
Expand Down
96 changes: 93 additions & 3 deletions example/src/Examples/DialogExample.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@ import {
DialogWithLoadingIndicator,
DialogWithLongText,
DialogWithRadioBtns,
NewDialogWithCustomColors,
NewDialogWithDismissableBackButton,
NewDialogWithIcon,
NewDialogWithLoadingIndicator,
NewDialogWithLongText,
NewDialogWithRadioBtns,
NewUndismissableDialog,
UndismissableDialog,
} from './Dialogs';
import ScreenWrapper from '../ScreenWrapper';
Expand Down Expand Up @@ -79,6 +86,57 @@ const DialogExample = () => {
Dismissable back button
</Button>
)}
<Button
mode="outlined"
onPress={_toggleDialog('dialog8')}
style={styles.button}
>
Long text (props)
</Button>
<Button
mode="outlined"
onPress={_toggleDialog('dialog9')}
style={styles.button}
>
Radio buttons (props)
</Button>
<Button
mode="outlined"
onPress={_toggleDialog('dialog10')}
style={styles.button}
>
Progress indicator (props)
</Button>
<Button
mode="outlined"
onPress={_toggleDialog('dialog11')}
style={styles.button}
>
Undismissable Dialog (props)
</Button>
<Button
mode="outlined"
onPress={_toggleDialog('dialog12')}
style={styles.button}
>
Custom colors (props)
</Button>
<Button
mode="outlined"
onPress={_toggleDialog('dialog13')}
style={styles.button}
>
With icon (props)
</Button>
{Platform.OS === 'android' && (
<Button
mode="outlined"
onPress={_toggleDialog('dialog14')}
style={styles.button}
>
Dismissable back button (props)
</Button>
)}
<DialogWithLongText
visible={_getVisible('dialog1')}
close={_toggleDialog('dialog1')}
Expand All @@ -103,10 +161,42 @@ const DialogExample = () => {
visible={_getVisible('dialog6')}
close={_toggleDialog('dialog6')}
/>
<DialogWithDismissableBackButton
visible={_getVisible('dialog7')}
close={_toggleDialog('dialog7')}
{Platform.OS === 'android' && (
<DialogWithDismissableBackButton
visible={_getVisible('dialog7')}
close={_toggleDialog('dialog7')}
/>
)}
<NewDialogWithLongText
visible={_getVisible('dialog8')}
close={_toggleDialog('dialog8')}
/>
<NewDialogWithRadioBtns
visible={_getVisible('dialog9')}
close={_toggleDialog('dialog9')}
/>
<NewDialogWithLoadingIndicator
visible={_getVisible('dialog10')}
close={_toggleDialog('dialog10')}
/>
<NewUndismissableDialog
visible={_getVisible('dialog11')}
close={_toggleDialog('dialog11')}
/>
<NewDialogWithCustomColors
visible={_getVisible('dialog12')}
close={_toggleDialog('dialog12')}
/>
<NewDialogWithIcon
visible={_getVisible('dialog13')}
close={_toggleDialog('dialog13')}
/>
{Platform.OS === 'android' && (
<NewDialogWithDismissableBackButton
visible={_getVisible('dialog14')}
close={_toggleDialog('dialog14')}
/>
)}
</ScreenWrapper>
);
};
Expand Down
13 changes: 3 additions & 10 deletions example/src/Examples/Dialogs/DialogWithIcon.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
import { StyleSheet } from 'react-native';

import { Button, Portal, Dialog, Palette } from 'react-native-paper';

import { TextComponent } from './DialogTextComponent';
Expand All @@ -15,11 +13,11 @@ const DialogWithIcon = ({
<Portal>
<Dialog onDismiss={close} visible={visible}>
<Dialog.Icon icon="alert" />
<Dialog.Title style={styles.title}>Dialog with Icon</Dialog.Title>
<Dialog.Title>Dialog with Icon</Dialog.Title>
<Dialog.Content>
<TextComponent>
This is a dialog with new component called DialogIcon. When icon is
displayed you should center the header.
This is a dialog with a component called DialogIcon. When the icon
is displayed, the title is centered automatically.
</TextComponent>
</Dialog.Content>
<Dialog.Actions>
Expand All @@ -33,9 +31,4 @@ const DialogWithIcon = ({
);
};

const styles = StyleSheet.create({
title: {
textAlign: 'center',
},
});
export default DialogWithIcon;
Loading