Material.MAUI 0.0.1

Material.MAUI

A modern, comprehensive port and evolution of XF.Material for .NET MAUI.

Material.MAUI provides a complete library of Material Design (Material 2/3 inspired) UI controls, dynamic theme management, typography scales, customizable surfaces, elevated cards, and a powerful modal dialog/snackbar system for cross-platform .NET MAUI applications.

---

Table of Contents

• Features
• Platform Support
• Installation
• Getting Started
  • 1. Register in MauiProgram.cs
  • 2. Initialize Resources
• Theming & Customization
  • Color System
  • Custom Initialization
  • Runtime Theme Switching (Dark Mode)
  • Typography & TypeScale
• Controls & Component Catalog
  • Buttons & Actions
  • Text Fields & Inputs
  • Selection Controls
  • Surfaces, Cards & Layouts
  • Chips, Badges & Indicators
  • Search & Navigation
• Dialogs & Snackbars
  • Alerts & Confirmations
  • Text Input Dialog
  • Single & Multiple Choice Dialogs
  • Loading Dialogs & Lottie Animations
  • Snackbars
• Migrating from XF.Material
• License

---

Features

• Full Material Control Suite: Over 25+ styled Material controls including buttons, text fields, cards, chips, badges, sheets, and menus.
• Dynamic Theming Engine: Light and dark mode support with runtime palette switching that updates all controls and dialogs instantly.
• Built-in Material Icons: Bundled Material Design icon font accessible directly in XAML with glyph constants (MaterialIcons.Star, MaterialIcons.Magnify, etc.).
• Async Dialog & Snackbar System: Rich modal alerts, inputs, single/multi-choice dialogs, action sheets, snackbars, and loading dialogs.
• SkiaSharp Lottie Loading Support: Seamless integration with SkiaSharp for animated Lottie loading dialogs.
• Performance Optimized: Full support for .NET MAUI XAML Source Generation (MauiXamlInflator=SourceGen) and minimal overhead.

---

Platform Support

Platform	Minimum Supported Version
Android	API 21+ (Android 5.0 Lollipop or newer)
iOS	iOS 15.0+
Mac Catalyst	macOS 12.0+ (Mac Catalyst 15.0+)
Windows	Windows 10 build 17763+ (WinUI 3 / Windows App SDK)

---

Installation

Add the NuGet package to your .NET MAUI application project:

dotnet add package Material.MAUI

Or via the Package Manager Console:

Install-Package Material.MAUI

---

Getting Started

1. Register in MauiProgram.cs

Call .UseMauiMaterial() on your MauiAppBuilder during app bootstrapping:

using MAUI.Material;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseMauiMaterial() // Registers MAUI.Material handlers, fonts, and SkiaSharp
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

        return builder.Build();
    }
}

2. Initialize Resources

You can initialize the Material resources in one of two ways:

Option A: Automatic via C# (Recommended)

Simply call Material.Initialize(this) in your App.xaml.cs constructor. This automatically injects the MaterialResources dictionary, enables system theme tracking, and manages light/dark transitions without needing any edits in App.xaml:

using MAUI.Material;

public partial class App : Application
{
    public App()
    {
        InitializeComponent();
        Material.Initialize(this); // Automatically merges resources and enables auto-theming
    }
}

Option B: Declarative via App.xaml (Pure XAML / Design-Time Preview)

If you prefer a pure XAML approach or want XAML Hot Reload / Designer previews without C# setup, merge MaterialResources directly into App.xaml:

<Application
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:material="clr-namespace:MAUI.Material.Resources;assembly=MAUI.Material"
    x:Class="MyMauiApp.App">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <material:MaterialResources />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Add the XML namespace to your XAML pages:

xmlns:material="clr-namespace:MAUI.Material;assembly=MAUI.Material"

---

Theming & Customization

Color System

MAUI.Material implements the standard Material color roles:

Resource Key	Purpose	Default Light	Default Dark
Material.Color.Primary	Primary brand color	#6200EE	#BB86FC
Material.Color.PrimaryVariant	Darker primary shade	#3700B3	#3700B3
Material.Color.Secondary	Accent and action components	#03DAC6	#03DAC6
Material.Color.SecondaryVariant	Darker secondary shade	#018786	#03DAC6
Material.Color.Background	App background	#FFFFFF	#121212
Material.Color.Surface	Surfaces for cards, sheets, dialogs	#FFFFFF	#1E1E1E
Material.Color.Error	Error indicators and validation	#B00020	#CF6679
Material.Color.OnPrimary	Text/icons on primary surface	#FFFFFF	#000000
Material.Color.OnSecondary	Text/icons on secondary surface	#000000	#000000
Material.Color.OnBackground	Text/icons on background	#000000	#FFFFFF
Material.Color.OnSurface	Text/icons on card/dialog surfaces	#000000	#FFFFFF
Material.Color.OnError	Text/icons on error surface	#FFFFFF	#000000

Custom Initialization

Configure your custom branding in App.xaml.cs after InitializeComponent():

using MAUI.Material;

public partial class App : Application
{
    public App()
    {
        InitializeComponent();

        Material.Initialize(this,
            configuration: new MaterialConfiguration
            {
                Colors = new MaterialColorConfiguration
                {
                    Primary = Color.FromArgb("#512BD4"),
                    PrimaryVariant = Color.FromArgb("#2B0B98"),
                    Secondary = Color.FromArgb("#6750A4"),
                    SecondaryVariant = Color.FromArgb("#4F378B"),
                    Background = Color.FromArgb("#FFFBFE"),
                    Surface = Colors.White,
                    OnBackground = Color.FromArgb("#1C1B1F"),
                    OnSurface = Color.FromArgb("#1C1B1F")
                },
                Fonts = new MaterialFontConfiguration
                {
                    H4 = "OpenSansRegular",
                    H5 = "OpenSansRegular",
                    H6 = "OpenSansSemibold",
                    Subtitle1 = "OpenSansRegular",
                    Subtitle2 = "OpenSansSemibold",
                    Body1 = "OpenSansRegular",
                    Body2 = "OpenSansRegular",
                    Button = "OpenSansSemibold"
                },
                Sizes = new MaterialSizeConfiguration
                {
                    ButtonHeight = 48,
                    ButtonCornerRadius = 8,
                    SliderHeight = 27
                }
            },
            darkConfiguration: new MaterialConfiguration
            {
                Colors = new MaterialColorConfiguration
                {
                    Primary = Color.FromArgb("#D0BCFF"),
                    Secondary = Color.FromArgb("#CCC2DC"),
                    Background = Color.FromArgb("#1C1B1F"),
                    Surface = Color.FromArgb("#2B2930"),
                    OnBackground = Color.FromArgb("#E6E1E5"),
                    OnSurface = Color.FromArgb("#E6E1E5")
                }
            });
    }
}

Runtime Theme Switching (Dark Mode)

Switch themes programmatically at runtime with a single call:

// Follow system setting
Material.SetTheme(AppTheme.Unspecified);

// Force light theme
Material.SetTheme(AppTheme.Light);

// Force dark theme
Material.SetTheme(AppTheme.Dark);

Typography & TypeScale

Apply preconfigured Material type-scale styles directly to standard MAUI controls or MaterialLabel:

<material:MaterialLabel Text="Display Headline" TypeScale="H4" />
<material:MaterialLabel Text="Body paragraph text" TypeScale="Body1" />
<material:MaterialLabel Text="Small caption" TypeScale="Caption" />


<Label Text="Subtitle" Style="{StaticResource Material.TypeScale.Subtitle1}" />

Available TypeScale options: H1, H2, H3, H4, H5, H6, Subtitle1, Subtitle2, Body1, Body2, Button, Caption, Overline.

---

Controls & Component Catalog

Buttons & Actions

MaterialButton

Supports Elevated, Outlined, Flat, and Text variants with configurable elevation, corner radius, and ripple states.

<material:MaterialButton
    Text="Elevated Button"
    ButtonType="Elevated"
    Elevation="2, 8" />

<material:MaterialButton
    Text="Outlined Button"
    ButtonType="Outlined" />

<material:MaterialButton
    Text="Text Button"
    ButtonType="Text" />

MaterialIconButton & MaterialFloatingActionButton

Tintable icon buttons with drop shadows and circular action buttons (Standard 56dp and Mini 40dp).

<material:MaterialIconButton
    ButtonType="Outlined"
    CornerRadius="24"
    TintColor="{DynamicResource Material.Color.Secondary}">
    <material:MaterialIconButton.Image>
        <FontImageSource
            FontFamily="{x:Static material:MaterialIcons.FontFamily}"
            Glyph="{x:Static material:MaterialIcons.InformationOutline}" />
    </material:MaterialIconButton.Image>
</material:MaterialIconButton>


<material:MaterialFloatingActionButton
    Clicked="OnFloatingActionClicked">
    <material:MaterialFloatingActionButton.Image>
        <FontImageSource
            FontFamily="{x:Static material:MaterialIcons.FontFamily}"
            Glyph="{x:Static material:MaterialIcons.Plus}" />
    </material:MaterialFloatingActionButton.Image>
</material:MaterialFloatingActionButton>


<material:MaterialFloatingActionButton
    IsMini="True">
    <material:MaterialFloatingActionButton.Image>
        <FontImageSource
            FontFamily="{x:Static material:MaterialIcons.FontFamily}"
            Glyph="{x:Static material:MaterialIcons.Star}" />
    </material:MaterialFloatingActionButton.Image>
</material:MaterialFloatingActionButton>

MaterialSegmentedButton

A connected row of mutually exclusive button choices.

<material:MaterialSegmentedButton
    x:Name="DensitySegments"
    SelectedIndex="1"
    SelectedIndexChanged="OnDensityChanged" />

DensitySegments.Choices = new List<string> { "Compact", "Comfortable", "Spacious" };

---

Text Fields & Inputs

MaterialTextField

Filled Material text field with floating placeholder, validation error state, helper text, leading icon, character counter, and dropdown choices support.

<material:MaterialTextField
    Placeholder="Email address"
    HelperText="We'll never share your email"
    InputType="Email"
    LeadingIcon="email_icon.png"
    LeadingIconTintColor="{DynamicResource Material.Color.Primary}" />

<material:MaterialTextField
    Placeholder="Project Name"
    MaxLength="30"
    IsMaxLengthCounterVisible="True"
    HasError="False"
    ErrorText="Name is required" />


<material:MaterialTextField
    Placeholder="Role"
    Choices="{Binding UserRoles}"
    SelectedChoice="{Binding SelectedRole}" />

MaterialDateField

A date selection field with animated placeholder and date picker integration.

<material:MaterialDateField
    Placeholder="Date of Birth"
    Format="MMMM dd, yyyy"
    Date="{Binding BirthDate}" />

---

Selection Controls

MaterialRadioButton & MaterialRadioButtonGroup

<material:MaterialRadioButton
    Text="Enable notifications"
    IsSelected="True" />


<material:MaterialRadioButtonGroup
    x:Name="ThemeGroup"
    Orientation="Vertical"
    SelectedIndex="0"
    SelectedIndexChanged="OnThemeSelectionChanged" />

ThemeGroup.Choices = new[] { "System default", "Light", "Dark" };

MaterialCheckbox & MaterialCheckboxGroup

<material:MaterialCheckbox
    Text="Accept terms &amp; conditions"
    IsSelected="{Binding AcceptedTerms}" />


<material:MaterialCheckboxGroup
    x:Name="ComponentGroup"
    Orientation="Horizontal" />

ComponentGroup.Choices = new[] { "Buttons", "Cards", "Text fields" };
ComponentGroup.SelectedIndices = new[] { 0, 1 };

MaterialSwitch & MaterialSlider

<material:MaterialSwitch
    IsActivated="True"
    Toggled="OnSwitchToggled" />

<material:MaterialSlider
    Value="45"
    Minimum="0"
    Maximum="100" />

---

Surfaces, Cards & Layouts

MaterialCard & MaterialSurface

Elevated surfaces that automatically adapt to light/dark themes with custom shadows and rounded corners.

<material:MaterialCard
    Elevation="2"
    CornerRadius="8"
    Padding="16">
    <VerticalStackLayout Spacing="8">
        <material:MaterialLabel Text="Card Title" TypeScale="H6" />
        <material:MaterialLabel Text="Card content description goes here." TypeScale="Body2" />
    </VerticalStackLayout>
</material:MaterialCard>

<material:MaterialSurface
    Elevation="4"
    CornerRadius="16"
    Padding="20">
    <Label Text="Elevated Surface" />
</material:MaterialSurface>

MaterialDivider

<material:MaterialDivider Margin="0,16" />

MaterialBottomSheet

A modal bottom sheet surface for contextual actions and details.

var sheet = new MaterialBottomSheet
{
    Content = new VerticalStackLayout
    {
        Padding = 20,
        Spacing = 12,
        Children =
        {
            new MaterialLabel { Text = "Actions", TypeScale = MaterialTypeScale.H6 },
            new MaterialButton { Text = "Share", ButtonType = MaterialButtonType.Text },
            new MaterialButton { Text = "Delete", ButtonType = MaterialButtonType.Text }
        }
    }
};

await sheet.ShowAsync();

MaterialBanner

Informational top banners for high-priority status and alerts.

<material:MaterialBanner
    Text="A software update is available for download."
    ButtonText="Update Now"
    ButtonClicked="OnUpdateClicked" />

---

Chips, Badges & Indicators

MaterialChip

Interactive chips with leading icons, trailing action buttons (e.g. remove), and tap commands.

<material:MaterialChip
    Text="Filtered by: Mobile"
    ActionImage="close_icon.png"
    ActionImageTapped="OnRemoveFilterClicked" />

MaterialBadge

Badge indicators that anchor over any content (like icon buttons or avatars).

<material:MaterialBadge Text="5">
    <material:MaterialIconButton
        ButtonType="Outlined">
        <material:MaterialIconButton.Image>
            <FontImageSource
                FontFamily="{x:Static material:MaterialIcons.FontFamily}"
                Glyph="{x:Static material:MaterialIcons.Bell}" />
        </material:MaterialIconButton.Image>
    </material:MaterialIconButton>
</material:MaterialBadge>

MaterialLinearProgressIndicator & MaterialCircularLoadingView

<material:MaterialLinearProgressIndicator Value="0.65" />


<material:MaterialLinearProgressIndicator IsIndeterminate="True" />


<material:MaterialCircularLoadingView
    IsRunning="True"
    WidthRequest="40"
    HeightRequest="40" />

---

Search & Navigation

MaterialSearchBar

Rounded pill search bar with leading icon, automatic clear button, and search commands.

<material:MaterialSearchBar
    Placeholder="Search components..."
    SearchButtonPressed="OnSearchQuerySubmitted"
    SearchCommand="{Binding PerformSearchCommand}" />

MaterialTabs

Top navigation tabs with indicator bars.

<material:MaterialTabs
    x:Name="SampleTabs"
    SelectedIndex="0"
    SelectedIndexChanged="OnTabSelected" />

SampleTabs.Items = new List<string> { "Overview", "Controls", "Theme" };

MaterialNavigationPage

Custom NavigationPage supporting centered AppBar titles, elevations, and theme colors:

protected override Window CreateWindow(IActivationState? activationState)
{
    return new Window(new MaterialNavigationPage(new MainPage()));
}

---

Dialogs & Snackbars

The MaterialDialog API provides asynchronous, awaitable dialogs and snackbars that automatically adopt your app's theme colors.

Alerts & Confirmations

using MAUI.Material;

// Simple Alert
await MaterialDialog.Instance.AlertAsync(
    "Your changes have been saved.",
    "Success");

// Two-Button Confirmation Dialog
bool? confirmed = await MaterialDialog.Instance.ConfirmAsync(
    "Are you sure you want to delete this record?",
    "Confirm Delete",
    confirmingText: "Delete",
    dismissiveText: "Cancel");

if (confirmed == true)
{
    // Perform delete action
}

Text Input Dialog

string input = await MaterialDialog.Instance.InputAsync(
    title: "New Project",
    message: "Enter the project name:",
    inputPlaceholder: "Project Name",
    confirmingText: "Create",
    dismissiveText: "Cancel");

Single & Multiple Choice Dialogs

// Action Sheet
int selectedAction = await MaterialDialog.Instance.SelectActionAsync(
    title: "Choose Action",
    actions: new[] { "Edit", "Duplicate", "Archive", "Delete" });

// Single Choice Radio Dialog
int selectedIndex = await MaterialDialog.Instance.SelectChoiceAsync(
    title: "Select Language",
    choices: new[] { "English", "Spanish", "French", "German" },
    selectedIndex: 0);

// Multiple Choice Checkbox Dialog
int[] selectedIndices = await MaterialDialog.Instance.SelectChoicesAsync(
    title: "Select Interests",
    choices: new[] { "Design", "Mobile", "Cloud", "AI" },
    selectedIndices: new[] { 0, 1 });

Loading Dialogs & Lottie Animations

Show an indeterminate loading indicator or an animated Lottie file:

// Default ActivityIndicator loading dialog
var loading = await MaterialDialog.Instance.LoadingDialogAsync("Signing in…");

// Perform background work
await Task.Delay(2000);

// Dismiss dialog
await loading.DismissAsync();

For Lottie animations, place your animation JSON file in Resources/Raw/ (e.g. material_loading.json):

var lottieDialog = await MaterialDialog.Instance.LoadingDialogAsync(
    message: "Processing payment…",
    lottieAnimation: "material_loading.json");

await ProcessPaymentAsync();
await lottieDialog.DismissAsync();

Snackbars

// Simple snackbar
await MaterialDialog.Instance.SnackbarAsync("Item added to cart.");

// Snackbar with action button
bool actionTapped = await MaterialDialog.Instance.SnackbarAsync(
    message: "Email sent.",
    actionButtonText: "Undo",
    msDuration: MaterialSnackbar.DurationLong);

if (actionTapped)
{
    // Undo sending email
}

---

Migrating from XF.Material

If you are upgrading a Xamarin.Forms project using XF.Material:

1. Replace using XF.Material.Forms; with using MAUI.Material;.
2. Replace using XF.Material.Forms.Resources; with using MAUI.Material.Resources;.
3. In MauiProgram.cs, add .UseMauiMaterial().
4. Update Material.Init(this, ...) to Material.Initialize(this, ...) (or continue using the Material.Init compatibility alias).
5. All original dialog methods (MaterialDialog.Instance.AlertAsync, ConfirmAsync, LoadingDialogAsync, SnackbarAsync, etc.) are 100% compatible.

---

License

MAUI.Material is licensed under the MIT License.