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.

In v2, the default for HxModal backdrop was static.
For v3, we decided to stick with Bootstrap's backdrop default of true for generic HxModal component (includes HxDialogBase) and the static is used only as default for HxMessageBox.

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.