# CurrieTechnologies.Razor.SweetAlert2 | | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![Blazor](BrandBlazor_nohalo_140x.png) <br/> ➕ <br/> ![SweetAlert2](https://raw.github.com/sweetalert2/sweetalert2/master/assets/swal2-logo.png) <br/> A beautiful, responsive, customizable, accessible (WAI-ARIA) replacement for JavaScript's popup boxes. <br/> All wrapped inside a Razor Component Library for use in Blazor Server and WebAssembly applications. <br/> ![SweetAlert2 in action](https://raw.github.com/sweetalert2/sweetalert2/master/assets/sweetalert2.gif) <br/> [See SweetAlert2 in action ↗](https://sweetalert2.github.io/) | | Master | Develop | Version | Downloads | Mergify | | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------: | | [![Build Status](https://dev.azure.com/michaeljcurrie136/CurrieTechnologies.Blazor/_apis/build/status/Basaingeal.Razor.SweetAlert2?branchName=master)](https://dev.azure.com/michaeljcurrie136/CurrieTechnologies.Blazor/_build/latest?definitionId=16&branchName=master) | [![Build Status](https://dev.azure.com/michaeljcurrie136/CurrieTechnologies.Blazor/_apis/build/status/Basaingeal.Razor.SweetAlert2?branchName=develop)](https://dev.azure.com/michaeljcurrie136/CurrieTechnologies.Blazor/_build/latest?definitionId=16&branchName=develop) | ![Nuget](https://img.shields.io/nuget/v/CurrieTechnologies.Razor.SweetAlert2.svg?style=popout) | ![Nuget](https://img.shields.io/nuget/dt/CurrieTechnologies.Razor.SweetAlert2) | [![mergify-status](https://img.shields.io/endpoint.svg?url=https://gh.mergify.io/badges/Basaingeal/Razor.SweetAlert2&style=popout)](https://mergify.io) | 👉 **Upgrading from v3.x to v4.x?** [Read the release notes!](https://github.com/Basaingeal/Razor.SweetAlert2/releases/tag/v4.0.0) 👉 **Upgrading from v4.x to v5.x?** [Read the release notes!](https://github.com/Basaingeal/Razor.SweetAlert2/releases/tag/v5.0.0) ## This package is for both Blazor Server Apps and Blazor WebAssembly Apps. It should be used instead of [`CurrieTechnologies.Blazor.SweetAlert2`](https://github.com/Basaingeal/Blazor.SweetAlert2) which is now deprecated. ### 🙌 Includes themes from the [Official SweetAlert2 Themes project](https://github.com/sweetalert2/sweetalert2-themes) 🙌 ## Installation ```sh Install-Package CurrieTechnologies.Razor.SweetAlert2 ``` Or install from the NuGet Package Manager ## Usage ### Register the service in your Startup file. ```csharp // Startup.cs public void ConfigureServices(IServiceCollection services) { ... services.AddSweetAlert2(); ... } ``` **NB:** For newer .NET 6 minimal project templates, this will actually be in `Program.cs` ```csharp // Program.cs ... builder.Services.AddSweetAlert2(); ``` ### OR If you want to use one of the Official SweetAlert2 themes: ```csharp // Startup.cs public void ConfigureServices(IServiceCollection services) { ... services.AddSweetAlert2(options => { options.Theme = SweetAlertTheme.Dark; }); ... } ``` _See [Configuration](#configuration) for more information._ ### Add the script tag Add this script tag in your root html file (Likely \_Host.cshtml for Blazor Server or index.html for Blazor WebAssembly), right under the framework script tag. (i.e `<script src="_framework/blazor.server.js"></script>` for Blazor Server or `<script src="_framework/blazor.webassembly.js"></script>` for Blazor WebAssembly) **NB:** In newer templates, this will be towards the bottom of `Pages/_Layout.cshtml` for Blazor Server or `wwwroot/index.html` for Blazor WebAssembly. ```html <script src="_content/CurrieTechnologies.Razor.SweetAlert2/sweetAlert2.min.js"></script> ``` **If you need to support IE11, this script tag is different. See [IE Compatibility](#ie-compatibility).** ### \_Imports.razor _Recommended:_ Add `@using CurrieTechnologies.Razor.SweetAlert2` to your `_Imports.razor` file, to avoid having to put the using call in every component that requires it. ### Inject the SweetAlertService into any Blazor component. ```razor // Sample.razor @inject SweetAlertService Swal; <button class="btn btn-primary" @onclick="@(async () => await Swal.FireAsync("Any fool can use a computer"))"> Try me! </button> ``` ## Examples The most basic message: ```csharp await Swal.FireAsync("Hello world!"); ``` A message signaling an error: ```csharp await Swal.FireAsync("Oops...", "Something went wrong!", "error"); ``` Handling the result of SweetAlert2 modal: ```csharp // async/await SweetAlertResult result = await Swal.FireAsync(new SweetAlertOptions { Title = "Are you sure?", Text = "You will not be able to recover this imaginary file!", Icon = SweetAlertIcon.Warning, ShowCancelButton = true, ConfirmButtonText = "Yes, delete it!", CancelButtonText = "No, keep it" }); if (!string.IsNullOrEmpty(result.Value)) { await Swal.FireAsync( "Deleted", "Your imaginary file has been deleted.", SweetAlertIcon.Success ); } else if (result.Dismiss == DismissReason.Cancel) { await Swal.FireAsync( "Cancelled", "Your imaginary file is safe :)", SweetAlertIcon.Error ); } // Promise/Task based Swal.FireAsync(new SweetAlertOptions { Title = "Are you sure?", Text = "You will not be able to recover this imaginary file!", Icon = SweetAlertIcon.Warning, ShowCancelButton = true, ConfirmButtonText = "Yes, delete it!", CancelButtonText = "No, keep it" }).ContinueWith(swalTask => { SweetAlertResult result = swalTask.Result; if (!string.IsNullOrEmpty(result.Value)) { Swal.FireAsync( "Deleted", "Your imaginary file has been deleted.", SweetAlertIcon.Success ); } else if (result.Dismiss == DismissReason.Cancel) { Swal.FireAsync( "Cancelled", "Your imaginary file is safe :)", SweetAlertIcon.Error ); } }); ``` ### [More examples can be found on the SweetAlert2 project site](https://sweetalert2.github.io/) ## Configuration In `Startup.cs` you have the opportunity to configure how `sweetalert2` will behave in your application. ### Theme With `SweetAlertServiceOptions.Theme` you can specify one of the official sweetalert2 themes to apply to your modal throughout your application. #### SetThemeForColorSchemePreference() With the `SweetAlertServiceOptions.SetThemeForColorSchemePreference()` method, you can specify which theme the user uses, based on the result of their `prefers-color-scheme` CSS media query. Most commonly this can be used to help create a dark version of your application, based on user preference. Browsers that do not support the `prefers-color-scheme` media query will fall back to the theme specified in `SweetAlertServiceOptions.Theme` #### Theme Examples If you want the default theme by default, and the dark theme if the user prefers a dark color scheme: ```csharp services.AddSweetAlert2(options => { options.SetThemeForColorSchemePreference(ColorScheme.Dark, SweetAlertTheme.Dark); }); ``` A dark theme by default, and a lighter theme if the user prefers a light color scheme: ```csharp services.AddSweetAlert2(options => { options.Theme = SweetAlertTheme.Dark; options.SetThemeForColorSchemePreference(ColorScheme.Light, SweetAlertTheme.Bootstrap4); }); ``` A minimal theme as a fallback, and a dark/light theme to match user preference: ```csharp services.AddSweetAlert2(options => { options.Theme = SweetAlertTheme.Minimal; options.SetThemeForColorSchemePreference(ColorScheme.Light, SweetAlertTheme.Default); options.SetThemeForColorSchemePreference(ColorScheme.Dark, SweetAlertTheme.Dark); }); ``` _See [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) for more information._ ### Default Settings If you want some settings globally applied to all of your SweetAlert2 dialogs, configure your default settings in `Startup.cs` ```csharp services.AddSweetAlert2(options => { options.DefaultOptions = new SweetAlertOptions { HeightAuto = false }; }); ``` These can be overriden in individual `FireAsync()` calls. **NB:** This will only apply to `FireAsync()` calls that take a `SweetAlertOptions` object as a parameter. The methods that take in primitive types bypass `SweetAlertOptions` entirely on both the C# and JS libraries. ## Notable differences from the JavaScript library - No methods that return an HTMLElement are included (e. g. `Swal.getHtmlContainer()`) - The value of a `SweetAlertResult` (`result.Value`) can only be a string. Numbers and booleans must be converted. Object must be parsed to/from JSON in your code. - `DidOpenAsync()`, `WillCloseAsync()`, `WillOpenAsync()`, and `DidCloseAsync()` can all take asynchronous callbacks. 🎉 (none will return an HTMLElement though.) - No support for `<optgroup>` in the select input type. - No async option for `InputOptions` or `InputValue` - Callbacks must be passed inside of objects specifically designed for the given callback property. e.g. the `InputValidator` property takes an `InputValidatorCallback` created like so: ```csharp new SweetAlertOptions { ... InputValidator = new InputValidatorCallback((string input) => input.Length == 0 ? "Please provide a value" : null, this), ... } ``` `this` is passed in so that the Blazor `EventCallback` used behind the scenes can trigger a re-render if the state of the calling component was changed in the callback. If the callback does not require the calling component to re-render, passing in `this` is optional. These callbacks are necessary because there is currently no way to create an `EventCallback` in Blazor that isn't a component parameter without using the `EventCallbackFactory` which is clunky. It also allows the callback to return a value that can be used by the SweetAlert2 library. (e.g. A validation message to show if input validation fails.) Native Blazor `EventCallback`s only return generic `Task`s. ## Browser compatibility | IE11\* | Edge | Chrome | Firefox | Safari | Opera | UC Browser | | ------ | ---- | ------ | ------- | ------ | ----- | ---------- | | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ### IE Compatibility\* IE Compatibility has been removed in `v5` due to `sweetalert2@11` dropping their support for it. If you need to support IE11, use `v4` or earlier, and use this script tag instead. (file size is about 35% larger) ```html <script src="_content/CurrieTechnologies.Razor.SweetAlert2/sweetAlert2.ieCompat.min.js"></script> ``` You will also likely need to utilize the [Blazor.Polyfill](https://github.com/Daddoon/Blazor.Polyfill) library, for general Blazor functionality in IE. ## Protestware Currently, the original `sweetalert2` library contains protestware to disable Russian websites using `sweetalert2` when visited by Russian-speaking users. This wrapper library bypasses the effects of that protestware, so there should be no undesired effects when using this library. ## Related projects - [SweetAlert2](https://sweetalert2.github.io/) - Original SweetAlert2 project