# HAVIT Blazor Bootstrap Component Library

HAVIT Blazor is a comprehensive, free Bootstrap 5.3 component library for ASP.NET Blazor applications. It provides a rich set of UI components including form inputs, data grids, modals, navigation elements, and more - all designed to integrate seamlessly with Blazor's component model. The library supports both Blazor Server and Blazor WebAssembly hosting models, with features like cascading parameters, two-way binding, and async event handling.

The library follows Bootstrap's design patterns while adding enterprise-ready features such as built-in validation support, customizable defaults through static settings, and extensive parameter configuration. Components are prefixed with "Hx" (e.g., HxButton, HxGrid, HxModal) and support both simple usage scenarios and advanced customization through settings objects, templates, and CSS class parameters.

---

## HxButton

Bootstrap button component with support for icons, spinners, tooltips, and form validation integration. Automatically shows a spinner during async click handlers and provides single-click protection.

```razor
@* Basic button with click handler *@
<HxButton Text="Click Me" Color="ThemeColor.Primary" OnClick="HandleClick" />

@* Button with icon and outline style *@
<HxButton Text="Save"
          Icon="BootstrapIcon.Save"
          Color="ThemeColor.Success"
          Outline="true"
          OnClick="SaveAsync" />

@* Button with spinner during async operation *@
<HxButton Text="Submit"
          Color="ThemeColor.Primary"
          OnClick="@(async () => await Task.Delay(2000))" />

@* Button with tooltip *@
<HxButton Text="Help"
          Color="ThemeColor.Info"
          Tooltip="Click for more information"
          TooltipPlacement="TooltipPlacement.Top" />

@* Form submit button with validation *@
<EditForm Model="@model" OnValidSubmit="HandleValidSubmit">
    <DataAnnotationsValidator />
    <HxInputText @bind-Value="model.Name" Label="Name" />
    <HxButton Type="submit"
              Text="Save"
              Color="ThemeColor.Primary"
              OnValidClick="HandleValidClick"
              OnInvalidClick="HandleInvalidClick" />
</EditForm>

@code {
    private async Task HandleClick() => await Task.CompletedTask;
    private async Task SaveAsync() => await Task.Delay(1000);
    private async Task HandleValidClick(MouseEventArgs args) => await SaveDataAsync();
    private async Task HandleInvalidClick(MouseEventArgs args) => ShowValidationErrors();
}
```

---

## HxGrid

Data grid component for displaying tabular data with support for client-side and server-side paging, sorting, selection, and infinite scrolling.

```razor
@* Basic grid with columns and data provider *@
<HxGrid TItem="Employee" DataProvider="LoadEmployees">
    <Columns>
        <HxGridColumn TItem="Employee" HeaderText="Name" ItemTextSelector="@(e => e.Name)" />
        <HxGridColumn TItem="Employee" HeaderText="Email" ItemTextSelector="@(e => e.Email)" />
        <HxGridColumn TItem="Employee" HeaderText="Department" ItemTextSelector="@(e => e.Department)"
                      SortKeySelector="@(e => e.Department)" />
        <HxGridColumn TItem="Employee" HeaderText="Salary" ItemTextSelector="@(e => e.Salary.ToString("C"))" />
    </Columns>
</HxGrid>

@* Grid with selection and custom row styling *@
<HxGrid TItem="Employee"
        DataProvider="LoadEmployees"
        SelectionEnabled="true"
        @bind-SelectedDataItem="selectedEmployee"
        PageSize="10"
        Striped="true"
        ItemRowCssClassSelector="@(e => e.IsActive ? "" : "table-secondary")">
    <Columns>
        <HxGridColumn TItem="Employee" HeaderText="Name" ItemTextSelector="@(e => e.Name)" />
        <HxGridColumn TItem="Employee" HeaderText="Status">
            <ItemTemplate Context="employee">
                <HxBadge Color="@(employee.IsActive ? ThemeColor.Success : ThemeColor.Secondary)">
                    @(employee.IsActive ? "Active" : "Inactive")
                </HxBadge>
            </ItemTemplate>
        </HxGridColumn>
    </Columns>
</HxGrid>

@* Grid with multi-selection *@
<HxGrid TItem="Employee"
        DataProvider="LoadEmployees"
        MultiSelectionEnabled="true"
        @bind-SelectedDataItems="selectedEmployees"
        PreserveSelection="true">
    <Columns>
        <HxGridColumn TItem="Employee" HeaderText="Name" ItemTextSelector="@(e => e.Name)" />
    </Columns>
</HxGrid>

@code {
    private Employee selectedEmployee;
    private HashSet<Employee> selectedEmployees = new();

    private async Task<GridDataProviderResult<Employee>> LoadEmployees(GridDataProviderRequest<Employee> request)
    {
        // Server-side implementation with paging and sorting
        var query = dbContext.Employees.AsQueryable();

        // Apply sorting from request
        foreach (var sorting in request.Sorting ?? Enumerable.Empty<SortingItem<Employee>>())
        {
            query = sorting.SortDirection == SortDirection.Ascending
                ? query.OrderBy(sorting.SortKeySelector)
                : query.OrderByDescending(sorting.SortKeySelector);
        }

        var totalCount = await query.CountAsync();
        var data = await query
            .Skip(request.StartIndex)
            .Take(request.Count ?? 10)
            .ToListAsync(request.CancellationToken);

        return new GridDataProviderResult<Employee>
        {
            Data = data,
            TotalCount = totalCount
        };
    }

    public class Employee
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Email { get; set; }
        public string Department { get; set; }
        public decimal Salary { get; set; }
        public bool IsActive { get; set; }
    }
}
```

---

## HxModal

Bootstrap modal dialog component with support for headers, bodies, footers, sizing, and programmatic show/hide control.

```razor
@* Basic modal with title and body *@
<HxButton Text="Open Modal" OnClick="() => modal.ShowAsync()" />

<HxModal @ref="modal" Title="Confirmation">
    <BodyTemplate>
        <p>Are you sure you want to proceed?</p>
    </BodyTemplate>
    <FooterTemplate>
        <HxButton Text="Cancel" Color="ThemeColor.Secondary" OnClick="() => modal.HideAsync()" />
        <HxButton Text="Confirm" Color="ThemeColor.Primary" OnClick="HandleConfirm" />
    </FooterTemplate>
</HxModal>

@* Large centered modal with custom header *@
<HxModal @ref="detailModal"
         Size="ModalSize.Large"
         Centered="true"
         Scrollable="true"
         OnClosed="HandleModalClosed">
    <HeaderTemplate>
        <h5 class="modal-title">
            <HxIcon Icon="BootstrapIcon.PersonCircle" /> User Details
        </h5>
    </HeaderTemplate>
    <BodyTemplate>
        <div style="height: 500px;">
            @* Long content that requires scrolling *@
        </div>
    </BodyTemplate>
</HxModal>

@* Modal with static backdrop (cannot close by clicking outside) *@
<HxModal @ref="editModal"
         Title="Edit Record"
         Backdrop="ModalBackdrop.Static"
         CloseOnEscape="false"
         OnHiding="HandleModalHiding">
    <BodyTemplate>
        <EditForm Model="@editModel">
            <HxInputText @bind-Value="editModel.Name" Label="Name" />
        </EditForm>
    </BodyTemplate>
</HxModal>

@code {
    private HxModal modal;
    private HxModal detailModal;
    private HxModal editModal;
    private EditModel editModel = new();

    private async Task HandleConfirm()
    {
        await ProcessConfirmation();
        await modal.HideAsync();
    }

    private void HandleModalClosed() => Console.WriteLine("Modal closed");

    private void HandleModalHiding(ModalHidingEventArgs args)
    {
        // Cancel closing if form has unsaved changes
        if (HasUnsavedChanges())
        {
            args.Cancel = true;
        }
    }
}
```

---

## HxOffcanvas

Bootstrap offcanvas (drawer) component for side panels, typically used for navigation menus or detail views.

```razor
@* Basic offcanvas from the right *@
<HxButton Text="Open Drawer" OnClick="() => offcanvas.ShowAsync()" />

<HxOffcanvas @ref="offcanvas" Title="Settings" Placement="OffcanvasPlacement.End">
    <BodyTemplate>
        <HxInputText @bind-Value="settings.Theme" Label="Theme" />
        <HxSwitch @bind-Value="settings.DarkMode" Label="Dark Mode" />
    </BodyTemplate>
    <FooterTemplate>
        <HxButton Text="Save" Color="ThemeColor.Primary" OnClick="SaveSettings" />
    </FooterTemplate>
</HxOffcanvas>

@* Large offcanvas from the left with custom size *@
<HxOffcanvas @ref="filterOffcanvas"
             Title="Filters"
             Placement="OffcanvasPlacement.Start"
             Size="OffcanvasSize.Large"
             Backdrop="OffcanvasBackdrop.Static">
    <BodyTemplate>
        <HxFilterForm @ref="filterForm" TModel="FilterModel" Model="filter">
            <HxInputText @bind-Value="filter.SearchText" Label="Search" />
            <HxSelect TItem="string" TValue="string"
                      @bind-Value="filter.Category"
                      Data="categories"
                      Label="Category" />
        </HxFilterForm>
    </BodyTemplate>
</HxOffcanvas>

@code {
    private HxOffcanvas offcanvas;
    private HxOffcanvas filterOffcanvas;
    private SettingsModel settings = new();
    private FilterModel filter = new();
    private List<string> categories = new() { "All", "Active", "Archived" };

    private async Task SaveSettings()
    {
        await SaveSettingsToDb();
        await offcanvas.HideAsync();
    }
}
```

---

## HxInputText

Text input component with Bootstrap styling, label support, floating labels, and validation integration.

```razor
@* Basic text input with label *@
<HxInputText @bind-Value="model.Name" Label="Full Name" />

@* Password input *@
<HxInputText @bind-Value="model.Password" Label="Password" Type="InputType.Password" />

@* Email input with placeholder *@
<HxInputText @bind-Value="model.Email"
             Label="Email Address"
             Type="InputType.Email"
             Placeholder="user@example.com" />

@* Input with floating label *@
<HxInputText @bind-Value="model.Username"
             Label="Username"
             LabelType="LabelType.Floating" />

@* Input with input groups *@
<HxInputText @bind-Value="model.Website"
             Label="Website"
             InputGroupStartText="https://" />

@* Input with validation and hint *@
<EditForm Model="@model">
    <DataAnnotationsValidator />
    <HxInputText @bind-Value="model.Phone"
                 Label="Phone Number"
                 Type="InputType.Tel"
                 Hint="Format: +1 (555) 123-4567" />
    <HxValidationMessage For="() => model.Phone" />
</EditForm>

@code {
    private FormModel model = new();

    public class FormModel
    {
        [Required]
        [StringLength(100)]
        public string Name { get; set; }

        [Required]
        [EmailAddress]
        public string Email { get; set; }

        public string Username { get; set; }
        public string Password { get; set; }
        public string Website { get; set; }

        [Phone]
        public string Phone { get; set; }
    }
}
```

---

## HxSelect

Dropdown select component for single-item selection from a list of options.

```razor
@* Basic select with enum values *@
<HxSelect TItem="Priority" TValue="Priority"
          @bind-Value="selectedPriority"
          Data="Enum.GetValues<Priority>()"
          Label="Priority"
          Nullable="true"
          NullText="-- Select Priority --" />

@* Select with custom object data *@
<HxSelect TItem="Country" TValue="int"
          @bind-Value="selectedCountryId"
          Data="countries"
          ValueSelector="@(c => c.Id)"
          TextSelector="@(c => c.Name)"
          Label="Country"
          AutoSort="true" />

@* Select with disabled items *@
<HxSelect TItem="Product" TValue="int"
          @bind-Value="selectedProductId"
          Data="products"
          ValueSelector="@(p => p.Id)"
          TextSelector="@(p => p.Name)"
          ItemDisabledSelector="@(p => !p.InStock)"
          Label="Product" />

@code {
    private Priority selectedPriority;
    private int selectedCountryId;
    private int selectedProductId;

    private List<Country> countries = new()
    {
        new() { Id = 1, Name = "United States" },
        new() { Id = 2, Name = "Canada" },
        new() { Id = 3, Name = "United Kingdom" }
    };

    private List<Product> products = new()
    {
        new() { Id = 1, Name = "Widget A", InStock = true },
        new() { Id = 2, Name = "Widget B", InStock = false }
    };

    public enum Priority { Low, Medium, High, Critical }
    public class Country { public int Id; public string Name; }
    public class Product { public int Id; public string Name; public bool InStock; }
}
```

---

## HxAutosuggest

Autocomplete/typeahead input component with dynamic suggestions based on user input.

```razor
@* Basic autosuggest with data provider *@
<HxAutosuggest TItem="City" TValue="int"
               @bind-Value="selectedCityId"
               DataProvider="SearchCities"
               ValueSelector="@(c => c.Id)"
               TextSelector="@(c => c.Name)"
               ItemFromValueResolver="GetCityById"
               Label="City"
               Placeholder="Start typing to search..."
               MinimumLength="2"
               Delay="300" />

@* Autosuggest with custom item template *@
<HxAutosuggest TItem="User" TValue="int"
               @bind-Value="selectedUserId"
               DataProvider="SearchUsers"
               ValueSelector="@(u => u.Id)"
               TextSelector="@(u => u.DisplayName)"
               ItemFromValueResolver="GetUserById"
               Label="Assign To">
    <ItemTemplate Context="user">
        <div class="d-flex align-items-center">
            <img src="@user.AvatarUrl" class="rounded-circle me-2" width="24" />
            <div>
                <strong>@user.DisplayName</strong>
                <small class="text-muted d-block">@user.Email</small>
            </div>
        </div>
    </ItemTemplate>
    <EmptyTemplate>
        <div class="text-muted p-2">No users found</div>
    </EmptyTemplate>
</HxAutosuggest>

@code {
    private int selectedCityId;
    private int selectedUserId;

    private async Task<AutosuggestDataProviderResult<City>> SearchCities(AutosuggestDataProviderRequest request)
    {
        var cities = await dbContext.Cities
            .Where(c => c.Name.Contains(request.UserInput))
            .Take(10)
            .ToListAsync(request.CancellationToken);

        return new AutosuggestDataProviderResult<City> { Data = cities };
    }

    private async Task<City> GetCityById(int cityId)
    {
        return await dbContext.Cities.FindAsync(cityId);
    }

    private async Task<AutosuggestDataProviderResult<User>> SearchUsers(AutosuggestDataProviderRequest request)
    {
        var users = await userService.SearchAsync(request.UserInput, request.CancellationToken);
        return new AutosuggestDataProviderResult<User> { Data = users };
    }

    private async Task<User> GetUserById(int userId) => await userService.GetByIdAsync(userId);

    public class City { public int Id; public string Name; }
    public class User { public int Id; public string DisplayName; public string Email; public string AvatarUrl; }
}
```

---

## HxMessenger

Toast notification service for displaying temporary messages to users. Requires `HxMessenger` component in layout and `IHxMessengerService` injection.

```razor
@* In MainLayout.razor or App.razor *@
<HxMessenger Position="ToastContainerPosition.BottomEnd" />

@* In a page or component *@
@inject IHxMessengerService Messenger

<HxButton Text="Show Success" Color="ThemeColor.Success"
          OnClick="ShowSuccess" />
<HxButton Text="Show Error" Color="ThemeColor.Danger"
          OnClick="ShowError" />
<HxButton Text="Show Info" Color="ThemeColor.Info"
          OnClick="ShowInfo" />

@code {
    private void ShowSuccess()
    {
        Messenger.AddInformation("Record saved successfully!");
    }

    private void ShowError()
    {
        Messenger.AddError("Failed to save record. Please try again.");
    }

    private void ShowInfo()
    {
        Messenger.AddMessage(new MessengerMessage
        {
            Title = "Notification",
            Text = "You have 3 new messages",
            Color = ThemeColor.Primary,
            AutohideDelay = 5000 // 5 seconds
        });
    }
}
```

---

## HxSidebar

Responsive navigation sidebar component with collapsible items and mobile support.

```razor
<HxSidebar @bind-Collapsed="sidebarCollapsed">
    <HeaderTemplate>
        <HxSidebarBrand>
            <img src="/logo.png" alt="Logo" height="32" />
            <span class="ms-2">My App</span>
        </HxSidebarBrand>
    </HeaderTemplate>
    <ItemsTemplate>
        <HxSidebarItem Text="Dashboard"
                       Icon="BootstrapIcon.House"
                       Href="/"
                       Match="NavLinkMatch.All" />
        <HxSidebarItem Text="Users"
                       Icon="BootstrapIcon.People">
            <SubitemsTemplate>
                <HxSidebarItem Text="All Users" Href="/users" />
                <HxSidebarItem Text="Add User" Href="/users/add" />
                <HxSidebarItem Text="Roles" Href="/users/roles" />
            </SubitemsTemplate>
        </HxSidebarItem>
        <HxSidebarItem Text="Reports"
                       Icon="BootstrapIcon.GraphUp"
                       Href="/reports" />
        <HxSidebarItem Text="Settings"
                       Icon="BootstrapIcon.Gear"
                       Href="/settings" />
    </ItemsTemplate>
    <FooterTemplate Context="context">
        <div class="p-3">
            <small class="text-muted">
                @if (!context.SidebarCollapsed)
                {
                    <span>Logged in as @userName</span>
                }
            </small>
        </div>
    </FooterTemplate>
</HxSidebar>

@code {
    private bool sidebarCollapsed = false;
    private string userName = "John Doe";
}
```

---

## HxAlert

Bootstrap alert component for displaying contextual feedback messages.

```razor
@* Basic alerts *@
<HxAlert Color="ThemeColor.Success">Record saved successfully!</HxAlert>
<HxAlert Color="ThemeColor.Danger">An error occurred while processing your request.</HxAlert>
<HxAlert Color="ThemeColor.Warning">Please review your input before submitting.</HxAlert>
<HxAlert Color="ThemeColor.Info">System maintenance scheduled for tonight.</HxAlert>

@* Dismissible alert *@
<HxAlert Color="ThemeColor.Primary" Dismissible="true" OnDismissed="HandleDismissed">
    <strong>New feature!</strong> Check out our latest update.
</HxAlert>

@* Alert with icon *@
<HxAlert Color="ThemeColor.Danger">
    <HxIcon Icon="BootstrapIcon.ExclamationTriangle" CssClass="me-2" />
    <strong>Error:</strong> Unable to connect to the server.
</HxAlert>

@code {
    private void HandleDismissed() => Console.WriteLine("Alert dismissed");
}
```

---

## HxTabPanel

Tab navigation component for organizing content into switchable panels.

```razor
<HxTabPanel>
    <HxTab Id="general" Title="General">
        <Content>
            <HxInputText @bind-Value="model.Name" Label="Name" />
            <HxInputText @bind-Value="model.Description" Label="Description" />
        </Content>
    </HxTab>
    <HxTab Id="settings" Title="Settings">
        <TitleTemplate>
            <HxIcon Icon="BootstrapIcon.Gear" CssClass="me-1" /> Settings
        </TitleTemplate>
        <Content>
            <HxSwitch @bind-Value="model.IsActive" Label="Active" />
            <HxSelect TItem="string" TValue="string" @bind-Value="model.Category"
                      Data="categories" Label="Category" />
        </Content>
    </HxTab>
    <HxTab Id="advanced" Title="Advanced" Enabled="@showAdvanced">
        <Content>
            <p>Advanced configuration options...</p>
        </Content>
    </HxTab>
</HxTabPanel>

@code {
    private Model model = new();
    private bool showAdvanced = true;
    private List<string> categories = new() { "A", "B", "C" };

    public class Model
    {
        public string Name { get; set; }
        public string Description { get; set; }
        public bool IsActive { get; set; }
        public string Category { get; set; }
    }
}
```

---

## HxAccordion

Bootstrap accordion component for displaying collapsible content panels.

```razor
<HxAccordion>
    <HxAccordionItem Title="Section 1" Expanded="true">
        <Content>
            <p>Content for the first section. This is expanded by default.</p>
        </Content>
    </HxAccordionItem>
    <HxAccordionItem Title="Section 2">
        <Content>
            <p>Content for the second section.</p>
        </Content>
    </HxAccordionItem>
    <HxAccordionItem>
        <HeaderTemplate>
            <HxIcon Icon="BootstrapIcon.QuestionCircle" CssClass="me-2" />
            <strong>FAQ</strong>
        </HeaderTemplate>
        <Content>
            <p>Frequently asked questions content...</p>
        </Content>
    </HxAccordionItem>
</HxAccordion>
```

---

## Service Registration

Register HAVIT Blazor services in your application's startup configuration.

```csharp
// Program.cs
using Havit.Blazor.Components.Web;
using Havit.Blazor.Components.Web.Bootstrap;

var builder = WebApplication.CreateBuilder(args);

// Add HAVIT Blazor services
builder.Services.AddHxServices();
builder.Services.AddHxMessenger();
builder.Services.AddHxMessageBoxHost();

// Configure global defaults (optional)
HxButton.Defaults.Color = ThemeColor.Primary;
HxButton.Defaults.Size = ButtonSize.Regular;
HxGrid.Defaults.PageSize = 20;
HxGrid.Defaults.Striped = true;
HxModal.Defaults.Centered = true;
HxInputText.Defaults.LabelType = LabelType.Floating;

var app = builder.Build();
```

---

## CSS and JavaScript Setup

Include the required CSS and JavaScript files in your application.

```html
<!-- In _Host.cshtml or index.html -->
<head>
    <!-- HAVIT Blazor Bootstrap CSS (includes Bootstrap 5.3) -->
    <link href="_content/Havit.Blazor.Components.Web.Bootstrap/bootstrap.min.css" rel="stylesheet" />
    <link href="_content/Havit.Blazor.Components.Web.Bootstrap/Havit.Blazor.Components.Web.Bootstrap.bundle.css" rel="stylesheet" />
</head>
<body>
    <!-- Your app content -->

    <!-- HAVIT Blazor Bootstrap JavaScript -->
    <script src="_content/Havit.Blazor.Components.Web.Bootstrap/bootstrap.bundle.min.js"></script>
    <script src="_content/Havit.Blazor.Components.Web.Bootstrap/Havit.Blazor.Components.Web.Bootstrap.bundle.js"></script>
</body>
```

---

HAVIT Blazor is designed for building enterprise-grade Blazor applications with a consistent, professional look and feel. The components integrate naturally with Blazor's component model, supporting two-way binding, cascading parameters, and EditForm validation. Common use cases include admin dashboards, data management interfaces, CRUD applications, and internal business tools where Bootstrap styling and responsive design are required.

The library follows a consistent pattern where each component has static `Defaults` that can be configured application-wide, instance-level `Settings` for shared configurations, and individual parameters for component-specific customization. This three-tier configuration approach allows for maximum flexibility while maintaining consistency across an application. Components also support extensive CSS customization through `CssClass` parameters and follow Bootstrap's utility class conventions for spacing, sizing, and responsiveness.