Migrating to v3

Migration your projects to version 3 is pretty easy.

1.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. Bootstrap CSS and JS #

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:

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-kenU1KFdBIe4zVF0s0G1M5b4hcpxyD9F7jL+jjXkk+Q2h455rYXK/7HAuoJl+0I4" crossorigin="anonymous"></script>

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 #

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:

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-kenU1KFdBIe4zVF0s0G1M5b4hcpxyD9F7jL+jjXkk+Q2h455rYXK/7HAuoJl+0I4" crossorigin="anonymous"></script>

3. 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 #

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 ShowValidationMessage #

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

4. Verify 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. HxInputDateRange predefined ranges #

[OPTIONAL] 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. Obsolete components #

[OPTIONAL] 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 🗙