|
| 1 | +--- |
| 2 | +title: How to display Alerts in your App |
| 3 | +sidebar_label: How to display Alerts |
| 4 | +--- |
| 5 | + |
| 6 | +To display an alert in your web application, you will need to use the Alert Component from the `@dhis2/ui` library. However, you do not need to install this library as the best practice is to display the alert using the `useAlert` hook from the `@dhis2/app-runtime` library. |
| 7 | + |
| 8 | +In this guide we'll walk you through, step by step, how to display an alert in your application and handle the different alerts states. |
| 9 | + |
| 10 | +## Prerequisites |
| 11 | + |
| 12 | +To be able to implement the alert in your application, you need to have the following: |
| 13 | + |
| 14 | +- A web application built using the DHIS2 Application Platform |
| 15 | +- A basic understanding of React hooks |
| 16 | + |
| 17 | +If you do not yet have a web application built using the DHIS2 Application Platform, you can follow the [Getting Started](/docs/quickstart/quickstart-web) guide to create a new application. |
| 18 | + |
| 19 | +## Step 1: Import the `useAlert` hook |
| 20 | + |
| 21 | +The `useAlert` hook is a custom hook provided by the `@dhis2/app-runtime` library. To use it, you need to import it in your file. |
| 22 | + |
| 23 | +```js |
| 24 | +import { useAlert } from '@dhis2/app-runtime' |
| 25 | +``` |
| 26 | + |
| 27 | +Now that you have imported the `useAlert` hook, you can use it in your component. |
| 28 | + |
| 29 | +## Step 2: Send a default alert notification |
| 30 | + |
| 31 | +Now that you have imported the `useAlert` hook, you can use it to send a default alert notification. The `useAlert` hook returns an object with two functions: `show` and `hide`. |
| 32 | + |
| 33 | +The `show` function is used to display the alert, while the `hide` function is used to hide the alert. After hiding (automatically or by code), the alert will be removed from the alert stack. But you can re-add it by calling the `show` function again. |
| 34 | + |
| 35 | +```js |
| 36 | +const App() => { |
| 37 | + // highlight-start |
| 38 | + const { show, hide } = useAlert('This is a default alert message') |
| 39 | + // highlight-end |
| 40 | + |
| 41 | + // Display the alert, somewhere later in your code |
| 42 | + // highlight-start |
| 43 | + show() |
| 44 | + // highlight-end |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +To hide the alert, you can call the `hide` function, anywhere in your code where you have access to the `hide` function. |
| 49 | + |
| 50 | +```js |
| 51 | +const App() => { |
| 52 | + // [...] |
| 53 | + // highlight-start |
| 54 | + hide() |
| 55 | + // highlight-end |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +## Step 3: Adding options to the alert |
| 60 | + |
| 61 | +You can also add options to the alert, such as the duration of the alert, the type of alert, and the action to be taken when the alert is clicked. |
| 62 | + |
| 63 | +```js |
| 64 | +const App() => { |
| 65 | + // highlight-start |
| 66 | + const { show, hide } = useAlert('This is a default alert message', { |
| 67 | + duration: 30000, // 30 seconds |
| 68 | + critical: true, // show the alert as critical |
| 69 | + permanent: true // don't auto-hide the alert |
| 70 | + }) |
| 71 | + // highlight-end |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +:::info All Options |
| 76 | +You can see the full list of options in the [AlertBar component documentation](/docs/ui/components/alertbar#props). |
| 77 | +::: |
| 78 | + |
| 79 | +## Step 4: Displaying dynamic alerts |
| 80 | + |
| 81 | +You can also display dynamic alerts by passing a function to the `useAlert` hook. This function will receive the arguments passed to the `show` function. |
| 82 | + |
| 83 | +The code below will be capable of displaying alerts with different messages and options depending on the arguments passed to the `show` function. Two of the states represented, in the image below: |
| 84 | + |
| 85 | + |
| 86 | + |
| 87 | +The first state is a critical alert with the message `Failed to update tb`, while the second state is a success alert with the message `Successfully updated tb`. |
| 88 | + |
| 89 | +```js |
| 90 | +const App() => { |
| 91 | + // highlight-start |
| 92 | + const { show, hide } = useAlert( |
| 93 | + ({ program, success }) => (success ? `Successfully updated ${program}` : `Failed to update ${program}`), |
| 94 | + ({ success }) => isActive ? { critical: true } : { success: true } |
| 95 | + ) |
| 96 | + // highlight-end |
| 97 | + |
| 98 | + // Display the alert, somewhere else in your code |
| 99 | + // highlight-start |
| 100 | + show({ program: 'tb', success: true }) |
| 101 | + // highlight-end |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +In the example above, the alert message will be displayed as `Failed to update tb` and will be shown as critical. However, if you were to call the `show` function with `success: true`, the alert would show with a success state and the message `Successfully updated tb`. Updating the name will also change the message displayed in the alert dynamically. |
| 106 | + |
| 107 | +This allows you to configure the Alert once and reuse it with different messages and options depending on the state of your application. |
| 108 | + |
| 109 | +## Conclusion |
| 110 | + |
| 111 | +In this guide, you learned how to display alerts in your application using the `useAlert` hook from the `@dhis2/app-runtime` library. You also learned how to handle different alert states and display dynamic alerts. You can now use this knowledge to display alerts in your application and provide feedback to your users. |
| 112 | + |
| 113 | +You can read more about the `useAlert` hook in the [official documentation](/docs/app-runtime/hooks/useAlert), and find all properties to be used in the `AlertBar` component in the [AlertBar documentation](/docs/ui/components/alertbar#props). |
| 114 | + |
| 115 | +## Additional Resources |
| 116 | + |
| 117 | +- [AlertBar Component Documentation](/docs/ui/components/alertbar) |
| 118 | +- [AlertBar Demo](pathname:///demo/?path=/story/alert-bar--states) |
0 commit comments