Migrating to v3

Migration your projects to version 3 is pretty easy.

1. Update references to our NuGet package

Update the Havit.Blazor.Components.Web.Bootstrap package through NuGet Package Manager or with following command:

dotnet add package Havit.Blazor.Components.Web.Bootstrap

2. Update Bootstrap CSS and JS references

CSS

If you are using Bootstrap CSS from CDN, update the following line in your HTML head section, it's either index.html or _Host.cshtml/_Layout.cshtml depending on whether you're running WebAssembly or Server:

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-iYQeCzEYFbKjA/T2uDLTpkwGzCiq6soy8tYaI1GyVh/UjpbCx/TYkiZhlZB6+fzT" crossorigin="anonymous">

If you are referencing our Bootstrap CSS build _content/Havit.Blazor.Components.Web.Bootstrap/bootstrap.css, it is updated automatically. If you are referencing your custom Bootstrap build/theme, upgrade it to Boostrap 5.2.

Bootstrap JavaScript Bundle

At the end of HTML <body> section of either index.html or _Host.cshtml/_Layout.cshtml update this line referencing Bootstrap JavaScript Bundle (with Popper) from CDN:

<!-- Bootstrap JavaScript Bundle with Popper -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.1/dist/js/bootstrap.bundle.min.js" integrity="sha384-u1OknCvxWvY5kfmNBILK2hRnQC3Pr17a+RTT6rIHI7NnikvbZlHgTPOOmMi466C8" crossorigin="anonymous"></script>

3. Resolve breaking changes ⚠️

3.1 HxOffcanvas backdrop

Replace the original boolean HxOffcanvas.BackdropEnabled parameter with new enum-based OffcanvasBackdrop HxOffcanvas.Backdrop:

<HxOffcanvas BackdropEnabled="false" ... />             @* v2 *@
<HxOffcanvas Backdrop="OffcanvasBackdrop.False" ... />  @* v3 *@

Same applies for OffcanvasSettings used for HxOffcanvas.Defaults.

3.2 HxModal backdrop

Replace the original boolean HxModal.UseStaticBackdrop parameter with new enum-based ModalBackdrop HxModal.Backdrop:

<HxModal UseStaticBackdrop="false" ... />       @* v2 *@
<HxModal Backdrop="ModalBackdrop.True" ... />   @* v3 *@

Same applies for ModalSettings used for HxModal.Defaults and HxMessageBox.Defaults.ModalSettings.

If you want to keep the original backdrop bahavior from v2, add following line to your Program.cs:

HxModal.Defaults.Backdrop = ModalBackdrop.Static;
3.3 HxGrid pager

If you were using PagerCssClass in v2, replace it with new PagerSettings parameter:

<HxGrid PagerCssClass="your-class" ... />                          @* v2 *@
<HxGrid PagerSettings="new() { CssClass = "your-class" }" ... />   @* v3 *@
3.4 HxAutosuggest first item highlighting

The HighlightFirstSuggestion parameter was removed. The component now highlights the first suggestion by default (cannot be disabled). Remove the parameter from your code (incl. HxAutosuggest.Settings and HxAutosuggest.Defaults).

3.5 Input components ShowValidationMessage

The ShowValidationMessage parameter was refactored. If you were using it to disable the validation message, use ValidationMessageMode="ValidationMessageMode.None" instead.

4. Verify your CSS customizations

Check your CSS customizations and adjust according to the new Bootstrap 5.2 and Havit.Blazor setup. Focus on these areas where there were some changes which might affect your visual:

  • check the Bootstrap 5.2 migration guide
  • double-check validation messages, where we changed the default setup (see the new floating styles)
  • check your sidebar

5. [OPTIONAL] Set default predefined date ranges for HxInputDateRange

In v3 we removed the default predefined date ranges in HxInputDateRange.Defaults.PredfefinedDateRanges. If you want your application to use the original set of predefined ranges, add this code to your application setup:

DateTime today = DateTime.Today;

DateTime thisMonthStart = new DateTime(today.Year, today.Month, 1);
DateTime thisMonthEnd = new DateTime(today.Year, today.Month, DateTime.DaysInMonth(today.Year, today.Month));
DateTime lastMonthStart = thisMonthStart.AddMonths(-1);
DateTime lastMonthEnd = new DateTime(lastMonthStart.Year, lastMonthStart.Month, DateTime.DaysInMonth(lastMonthStart.Year, lastMonthStart.Month));
DateTime thisYearStart = new DateTime(today.Year, 1, 1);
DateTime thisYearEnd = new DateTime(today.Year, 12, 31);
DateTime lastYearStart = thisYearStart.AddYears(-1);
DateTime lastYearEnd = thisYearEnd.AddYears(-1);

HxInputDateRange.Defaults.PredefinedDateRanges = new[]
	{
		new InputDateRangePredefinedRangesItem { Label = "This month", DateRange = new DateTimeRange(thisMonthStart, thisMonthEnd) },
		new InputDateRangePredefinedRangesItem { Label = "Last month", DateRange = new DateTimeRange(lastMonthStart, lastMonthEnd) },
		new InputDateRangePredefinedRangesItem { Label = "This year", DateRange = new DateTimeRange(thisYearStart, thisYearEnd) },
		new InputDateRangePredefinedRangesItem { Label = "Last year", DateRange = new DateTimeRange(lastYearStart, lastYearEnd) },
	};

6. [OPTIONAL] Replace obsolete components with new ones

We replaced HxInputCheckbox with new HxCheckbox and HxInputSwitch with new HxSwitch.
The original Label parameter is now Text (the Label parameter of new components has a different purpose, see HxCheckbox documentation).

<HxInputCheckbox Label="check this" ... />  @* v2 *@
<HxCheckbox Text="check this" ... />        @* v3 *@

<HxInputSwitch Label="check this" ... />    @* v2 *@
<HxSwitch Text="check this" ... />          @* v3 *@

The old components are marked as [Obsolete], which will cause compile-time warnings (or errors if escalation is configured).

7. Troubles?

If you experience any troubles migrating your project to v3, feel free to use the GitHub Discussions to place your question.
If you find anything what seems to be a bug, file it to our GitHub Issues.

An unhandled error has occurred. Reload 🗙