NimbleBlazor 20.14.6

.NET 8.0

dotnet add package NimbleBlazor --version 20.14.6

NuGet\Install-Package NimbleBlazor -Version 20.14.6

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="NimbleBlazor" Version="20.14.6" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="NimbleBlazor" Version="20.14.6" />
                    

                            Directory.Packages.props

<PackageReference Include="NimbleBlazor" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add NimbleBlazor --version 20.14.6

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: NimbleBlazor, 20.14.6"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package NimbleBlazor@20.14.6

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=NimbleBlazor&version=20.14.6
                    

                            Install as a Cake Addin

#tool nuget:?package=NimbleBlazor&version=20.14.6
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Nimble Blazor

Getting Started

Prerequisites

IDE:
- Windows with Visual Studio: For Blazor development on Windows, the suggested IDE is:
  - Visual Studio 2022 (Enterprise, if available): Choose the "ASP.NET and Web Development" Workload in the installer
  - Ensure Visual Studio is completely up to date (v17.11.2+): In Visual Studio click "Help" then "Check for Updates"
- Mac with Visual Studio Code: Install Visual Studio Code and open it. Open the Extensions pane ("Preferences" >> "Extensions"), and search for / install the ms-dotnettools.csharp extension.
.NET SDK: See the main contributing doc for the required version.

Creating a new Blazor project

The built-in Blazor template projects are good starting points. Starting with .NET 8, there's a unified Blazor Web App project type, which supports multiple render modes (see the Blazor render modes documentation for more information). Also see the "Supported Render Modes" section below.

Visual Studio: Choose "New" >> "Project", and pick "Blazor Web App". Choose the appropriate settings for Interactive Render Mode and Interactivity Location, based on your project's needs. VS Code: Create a new folder, then open it in VS Code. Choose "View" >> "Terminal", and type dotnet new blazor and press Enter, to create a new Blazor Web App. Open the Command Palette ("View" >> "Command Palette" or Ctrl-Shift-P), enter ".NET Generate Assets for Build and Debug" and press Enter.

Additional Resources: Microsoft tutorial: Build a web app with Blazor; dotnet new documentation

Reference NimbleBlazor in a Blazor project

Add a PackageReference to the NimbleBlazor NuGet package:
- Using the published NimbleBlazor NuGet package (recommended)
  - Visual Studio: "Project" >> "Manage NuGet Packages", pick "nuget.org" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button.
  - VS Code: Run the command dotnet add package NimbleBlazor --source https://api.nuget.org/v3/index.json --prerelease in the Terminal window.
- For Nimble developers, with a locally built NimbleBlazor NuGet (built from the Nimble repo):
  - Run npm run build, and then npm run pack -w @ni/nimble-blazor from the root of the Nimble repo
  - Visual Studio: "Project" >> "Manage NuGet Packages". Click the gear/Settings button. Add a new Package Source ("NimbleBlazor") as [NimbleRepoDirectory]\packages\blazor-workspace\dist and commit/ close Settings. Pick "NimbleBlazor" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button.
  - VS Code: Run the command dotnet add package NimbleBlazor --source [NimbleRepoDirectory]\packages\blazor-workspace\dist in the Terminal window.
Add required references to Blazor code
- Open _Imports.razor, and add a new line at the bottom: @using NimbleBlazor
- Open the HTML page (generally App.razor for Blazor Web Apps, or wwwroot/index.html for Blazor WebAssembly / Hybrid)
  
  At the bottom of the <head> section (right before </head>), add
```
<link href="_content/NimbleBlazor/nimble-tokens/css/fonts.css" rel="stylesheet" />
```
  At the bottom of the <body> section (right before </body>), add
```
<script src="_content/NimbleBlazor/nimble-components/all-components-bundle.min.js"></script>
```

Additional Resources: dotnet add package documentation

Use Nimble Blazor components

For a simple modification to the Blazor template project: open Index.razor and add the following code at the bottom, to add a Nimble text field that updates when a Nimble button is clicked:

<NimbleTextField Value="@ButtonClickStatus"></NimbleTextField>
<NimbleButton Appearance="ButtonAppearance.Outline" @onclick="OnButtonClicked">Click Me</NimbleButton>
@code {
    protected string ButtonClickStatus { get; set; } = string.Empty;
    private int _buttonClickCount = 0;

    private void OnButtonClicked(MouseEventArgs args)
    {
        _buttonClickCount++;
        ButtonClickStatus = $"Button Clicked {_buttonClickCount} times";
    }
}

To test out your changes, do "Debug" >> "Start without Debugging" in Visual Studio, or dotnet watch run in the VS Code Terminal.

More complete examples can be found in the Demo.Client/Server example projects.

Supported Render Modes

Nimble supports all of the Blazor render modes:

Interactive server-side rendering (interactive SSR) using Blazor Server: RenderMode.InteractiveServer
Interactive WebAssembly: Client-side rendering (CSR) using Blazor WebAssembly: RenderMode.InteractiveWebAssembly
Interactive Auto: Interactive SSR initially, then CSR on subsequent visits after the Blazor bundle is downloaded: RenderMode.InteractiveAuto
Static server-side rendering (static SSR): Default, when no render mode is specified
- ⚠️Warning: This render mode is not recommended for most use cases with Nimble. As the page is just rendered once server-side and then no state is maintained, you're unable to use event handlers or call methods on components. This also means that for components like the Nimble Table / Wafer Map, setting data can't be done via the component methods (because they'll have no effect if called).

Prerendering

Blazor with .NET 8 uses prerendering by default for interactive render modes. With it enabled, components are initially rendered server-side without event handlers connected, which could cause unexpected behavior (no effect when users interact with controls immediately after page load).

See the Blazor prerendering docs for information on how to opt out of prerendering.

Theming and Design Tokens

To use Nimble's theme-aware design tokens in a Blazor app, you should have a <NimbleThemeProvider> element as an ancestor to all of the Nimble components you use. The app's default layout (MainLayout.razor in the examples) is a good place to put the theme provider (as the root content of the page).

Best practices

Custom Blazor components should provide their own scoped CSS file (in addition to a separate .cs file for the template-independent logic). Providing a separate CSS file is necessary to access other Blazor styling mechanisms that are helpful to use.

Styling Razor components

Often you will need to provide CSS for the Razor components to control things like layout behaviors within a parent container. To accomplish this, in the scoped CSS file for the component containing the Razor component (e.g. NimbleTextField), you must use the ::deep pseudo-selector to target that component.

MyComponent.razor

<div>
    <NimbleTextField class="text-field"></NimbleTextField>
</div>

MyComponent.razor.css

::deep .text-field {
    flex: 1;
}

::deep targets all descendants in a component's scoped styles, so ::deep styles should be written as targeted as possible (typically adding CSS classes to the selector). Components also must be wrapped in a containing element in order to work with the ::deep pseudo-selector. For more info see the Microsoft docs.

Using Nimble Design Tokens (CSS/SCSS)

Blazor doesn't have built-in support for using/ building SCSS files, however Nimble's design tokens can be used as CSS variables (var(--ni-nimble-...)) in Blazor apps without any additional work.

For a full list of supported variable names, see the Nimble Storybook, "Tokens" >> "Theme-aware tokens".

Recommended: Nimble Tokens SCSS file support

In order to use the Nimble design tokens as SCSS in Blazor projects (which results in better IntelliSense and compile-time checking for the Nimble tokens and variables):

In the .csproj where you have a PackageReference to NimbleBlazor, add the following:

<PropertyGroup>
    <NimbleBlazor_CopyNimbleDesignTokens>true</NimbleBlazor_CopyNimbleDesignTokens>


</PropertyGroup>

Add a NuGet package reference to AspNetCore.SassCompiler in your Blazor Project.

Add a file sasscompiler.json to your project directory:

{
"Arguments": "--style=expanded --silence-deprecation=import --error-css --no-source-map"
}

By default, your Razor files and accompanying SCSS can be in Views, Pages, Shared, Components folders (or subfolders), and non-scoped SCSS can be in Styles (which will be placed in wwwroot/css after building).
See the package docs for additional options.

Build the project. This ensures the Nimble SCSS has been copied locally.
Add new SCSS files for your Razor components (e.g. MyComponent.razor.scss), and @import '../NimbleDesignTokens/tokens'; in it (updating the import relative path as needed).
Note: You can use @forward/@use with AspNetCore.SassCompiler, but IntelliSense currently only works correctly with @import.
Use the $ni-nimble-... variables in your Blazor application SCSS.

Other notes:

When using this approach, we recommend fully switching your app over to SCSS, including updating app CSS styles in wwwroot/css to instead be SCSS files in Styles.
SCSS compilation happens before the rest of Blazor's compilation, so it works fine with Blazor CSS isolation.
When using ::deep in an SCSS file (needed when targeting Nimble components specifically), Visual Studio may show a warning (which can be ignored): ::deep is only allowed in file names ending with ".razor.css" or ".cshtml.css". See aspnetcore#58572.

Localization (Optional)

Most user-visible strings displayed by Nimble components are provided by the client application and are expected to be localized by the application if necessary. However, some strings are built into Nimble components and are provided only in English.

To provide localized strings in a localized Blazor app:

Add the label providers as children of your <NimbleThemeProvider>:
- <NimbleLabelProviderCore>: Used for labels for all components besides the table
- <NimbleLabelProviderTable>: Used for labels for the table (and table sub-components / column types)
For each Nimble-provided label shown in the Label Provider Storybook documentation:
- Add a new entry for the label in a resource file (.resx). You can either add to an existing resx file, or create a new one just for the Nimble strings. The resource value should be the Nimble-provided English default string shown in Storybook.
- Follow standard Blazor localization patterns to localize the strings, and load the localized versions at runtime in your application.
- Provide Nimble the localized strings with the label provider APIs. For example, to provide the popupDismiss label on NimbleLabelProviderCore, if you load your string resources with a .NET IStringLocalizer instance, your label provider may look like the following:
```
<NimbleLabelProviderCore PopupDismiss="@LabelStringLocalizer["popupDismiss"]"></NimbleLabelProviderCore>
```

Using Nimble Blazor in a Blazor Hybrid app

Requirement: Microsoft.AspNetCore.Components.WebView v8.0.4+

This updated WebView package include a fix so that the JavaScript initialization code that Nimble/Spright Blazor uses gets loaded correctly. Note that if using the Microsoft.AspNetCore.Components.WebView.Wpf package, it only specifies a dependency of Microsoft.AspNetCore.Components.WebView v8.0+, so you may to add need an explicit dependency on Microsoft.AspNetCore.Components.WebView to ensure a recent enough version is included. The Demo.Hybrid project in the Blazor solution illustrates this setup.

Contributing

Follow the instructions in CONTRIBUTING.md to modify this library.

Product	Compatible and additional computed target framework versions.
.NET	net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net8.0
- Apache.Arrow (= 22.1.0)
- Microsoft.AspNetCore.Components.Web (>= 8.0.25)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
20.14.6	78	4/2/2026
20.14.5	82	4/1/2026
20.14.4	83	3/30/2026
20.14.3	93	3/24/2026
20.14.2	86	3/19/2026
20.14.1	94	3/18/2026
20.14.0	92	3/12/2026
20.13.7	98	3/2/2026
20.13.6	93	3/2/2026
20.13.5	99	3/2/2026
20.13.4	101	2/27/2026
20.13.3	100	2/23/2026
20.13.2	104	2/16/2026
20.13.1	117	2/11/2026
20.13.0	104	2/10/2026
20.12.4	228	2/5/2026
20.12.3	107	2/4/2026
20.12.2	108	2/4/2026
20.12.1	100	2/4/2026
20.12.0	105	2/4/2026