Release Notes
What changed in the ShellUI 0.4 line, and how to upgrade.
The full history is in RELEASE_NOTES.md on GitHub. For 0.3.x, see the v0.3 release notes.
v0.4.0
The 0.4 stable release. Compared with 0.3 it adds 19 components and three sign-in page blocks, compositional parts for eight more, shellui add all, doctor and migrate, .NET 8 and 9 support, and a CLI that keeps your changes on update. This section sums up the whole 0.4 line; the alpha sections below have the details.
New in 0.4
- Components. Kbd, Aspect Ratio, Button Group, Toggle Group, Input Group, Number Input, Stat Card, Timeline, Tree View, QR Code, Image Viewer and Chat with
chat-messageandchat-input(0.4.0-alpha.1), and since alpha.3:- Prompt Suggestions: clickable suggestion chips for an empty chat.
- Reasoning: a collapsible block that streams a model's thinking, open while
IsStreamingand folded to "Thought for N seconds" after. - Tool Call: a tool's name with a pending, running, done or error badge; it opens to show the arguments, result or error.
- Field: label, control, description and validation message as one unit, vertical or horizontal;
Forshows theEditForm's messages. - JSON Viewer: a highlighted, foldable JSON tree from a string or any object, with a copy button.
- Resizable is now a real panel group:
ResizablePanelGroup,ResizablePanel(DefaultSize,MinSize,MaxSize) andResizableHandle, dragged with the pointer or moved with the arrow keys, Home and End. The browser moves the panels and reports the sizes once, so dragging doesn't wait on Blazor Server. The oldResizablestays in the package, deprecated.
- Blocks.
init --dashboard 01|02wires a dashboard layout into the app, and the newauth-01,auth-02andauth-03blocks give apps that use ASP.NET Core Identity their own sign-in pages. - Compositional parts for Alert Dialog, Breadcrumb, Command, Form, Menubar, Pagination, Sheet and Drawer. Each mode is opt-in, so existing markup keeps working.
SonnerService.Clear()andDestructivecontext menu items.- .NET 8 and 9. The CLI runs on .NET 8 or later, and
ShellUI.Componentstargets .NET 8, 9 and 10. The 0.3 line needed .NET 10.
CLI
shellui add allinstalls every component except the page blocks;--exceptleaves out a component and everything that depends on it.shellui doctorchecks the project's setup and says how to fix each problem; it exits 1 on errors, so it can run in CI.shellui migraterewrites your pages for template API changes afterupdate:Input.InputVariant.X, the DatePicker and TimePickerSelected*parameters andPagination.OnPageChange. It shows each changed line and asks first (--dry-run,--yes), and points outCalendarhandlers that need aDateTime?.updatekeeps your changes and installs dependencies a component gained since you added it.addnever downgrades a NuGet package.removefollows yourComponentsPath.- One Tailwind CLI per machine in
~/.shellui/bin, with resumable downloads, instead of a copy in every project. - Razor class libraries:
initrecognises a library shared by several apps. See Razor Class Library.
See the CLI guide for each command.
Fixes since 0.4.0-alpha.3
addhung on .NET 8 and 9 apps. The CLI waited fordotnet add package, npm and Tailwind to exit before reading their output, so once a process wrote more than a pipe buffer both sides waited forever.shellui add allstopped on restoring Blazor-ApexCharts. Output is now read while the process runs.- The CLI didn't start on a machine with only .NET 9 (or a newer runtime). It now rolls forward to any .NET 8 or later runtime.
doctorsaidapp.csswas stale right after a build. Tailwind skips writing unchanged output, so the file kept an old timestamp. The build now touches it;updatebrings the change to projects set up by alpha.2 and alpha.3.list --installedsaid "0 available" (and--available"0 installed"). The summary now counts every target.- Safelist: classes passed to
Shell.Cn("…")and literals in ternaries never reachedshellui-classes.txt, so 198 classes were missing for apps that build their own Tailwind CSS from the package. - Everything fixed in 0.3.5 and 0.3.6 is included.
Breaking changes from 0.3
Calendar.SelectedDateChangedisEventCallback<DateTime?>. Handlers that take aDateTimemust take aDateTime?(shellui migratelists them).- CLI templates, after
shellui update:Input.InputVariantis nowInputVariant(newinput-variantstemplate); Stepper parts read the stepper'sActiveStepinstead of aCurrentStepparameter;ScrollAreadrops itsscrollbar-*classes;shellui add resizableinstalls the panel group.shellui migratefixes theInputVariantuses. - Still working but deprecated:
Pagination.OnPageChange,DatePicker.SelectedDate,TimePicker.SelectedTimeand the oldResizable.shellui migratemoves you off the first three.
Upgrading from 0.3
- CLI:
dotnet tool update -g ShellUI.CLI, then in each project commit, runshellui update, thenshellui migrate, and build.shellui doctorchecks the result. - NuGet package: update
ShellUI.Componentsto0.4.0. If you handleCalendar.SelectedDateChanged, change the handler's parameter toDateTime?. - If you used
Class="…!"to beat a component's own classes, you can drop the!.
The same steps upgrade a project on a 0.4 prerelease.
dotnet tool update -g ShellUI.CLI
shellui update
shellui migrate
shellui doctor
dotnet add package ShellUI.Components --version 0.4.0
Full changelog: v0.3.6...v0.4.0
v0.4.0-alpha.3
The third 0.4 prerelease. A component's Class now overrides its own classes, dialogs and sheets keep keyboard focus inside, add never downgrades your NuGet packages, and the CLI templates have been brought in line with the NuGet package, fixing several template bugs on the way. It also adds Razor class library support.
Improvements
Classoverrides a component's own classes.Shell.Cnused to join strings, so<Card Class="max-w-lg">on a component that setsmax-w-mdput both on the element and the stylesheet decided. Now, when two classes set the same CSS property under the same variants, the later one (yours) wins, like tailwind-merge:p-4replaces an earlierpx-2, text colour and text size stay separate, and unknown classes are kept. You no longer need the!modifier. The NuGet package and the CLI'sShell.csshare the same code.- Focus stays inside open overlays. Dialog, Alert Dialog, Sheet and Drawer keep Tab and Shift+Tab inside while they're open, and return focus to where it was when they close. The legacy (non-compositional) Sheet and Drawer panels now also take focus and close on Escape.
addnever downgrades a NuGet package. It used to set the exact version a component pins, so addingchartto an app on Blazor-ApexCharts 7 moved it back to 6.0.2. Now it reads the project'sPackageReference(orDirectory.Packages.props), adds a missing package or raises an older one, and leaves the same or newer, floating versions and ranges alone.- Razor class libraries.
initrecognises a library shared by several apps, prints what each app needs with the library's_contentpath, and adds its@usingto a root_Imports.razor. See Razor Class Library.
Fixes: CLI templates now match the package
The CLI templates and the NuGet package had drifted apart. They're reconciled (210 of 217 components identical, the rest differ by design), and a test now compares them. Bugs this fixed:
- Radio Group (template): clicking an item did nothing, because the group never passed itself to its items.
RadioGroupItemalso gainsDisabled. - ScrollArea (template): long content was clipped instead of scrolling.
HeightandMaxHeightnow size the scrolling element. - Date Picker (package): day 1 was always drawn under Sunday. It now sits under its real weekday, and the picker opens on the selected month.
- TimePicker:
Stepnow filters the minutes (it was ignored), the picker opens on the current value, and Cancel or an outside click closes it. - DateRangePicker (template) closes on an outside click; EmptyState (template) applies
Class. - Sheet and Drawer: clicks inside the panel no longer reach parent click handlers; the close button shows when only
Descriptionis set; the templates switch to compositional mode by themselves (noCompositional="true"needed). - Label renders
Foras theforattribute; FileUpload uses an inline SVG icon instead of the Material Symbols font; CarouselItem handles zero slides. - Pagination supports
@bind-CurrentPagein both copies and ignores clicks on the current page; Toast has success and warning variants,Position, auto-dismiss afterDuration(0 keeps it open) and a labelled close button; Skeleton hasVariant(default,circle,text); NavigationMenuItem is a dropdown whenTitleis set and a link or button otherwise. Table,Separator,Slider,Navbar,Checkbox,Switch,Tooltip,SidebarMenuButton,MenubarandThemeToggletemplates now match the package's markup and classes.
Breaking changes (CLI templates, after shellui update)
- Input variants moved out of the component:
Input.InputVariant.Erroris nowInputVariant.Error, from the newinput-variantstemplate inComponents/UI/Variants(likeButtonVariant).TextareagainsVariant,ReadOnly,OnFocusandOnBlurthroughtextarea-variants. - Stepper parts read the stepper's
ActiveStepinstead of taking aCurrentStepparameter, and the template gains the package's data-drivenStepItemsmode (StepItemcomes from the newstepper-modelstemplate). - ScrollArea drops its
scrollbar-*classes, which needed a Tailwind plugin nobody shipped. - Still working but deprecated:
Pagination.OnPageChange(use@bind-CurrentPage),DatePicker.SelectedDateandTimePicker.SelectedTime(useValue/@bind-Value).
shellui update installs the new input-variants, textarea-variants and stepper-models templates for you, and skips files you've changed since installing them.
Upgrading from 0.4.0-alpha.2
- CLI: update the tool, then run
shellui update. Commit first so you can review the changes, and fix anyInput.InputVariantand StepperCurrentStepuses (see above). - NuGet package: update
ShellUI.Componentsto0.4.0-alpha.3. - If you used
Class="…!"to beat a component's own classes, you can drop the!.
Upgrading from 0.3: follow the 0.4.0-alpha.1 and 0.4.0-alpha.2 notes below, then the steps above.
dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.3
dotnet add package ShellUI.Components --version 0.4.0-alpha.3
Full changelog: v0.4.0-alpha.2...v0.4.0-alpha.3
v0.4.0-alpha.2
The second 0.4 prerelease. It fixes shellui update, which could leave a project upgraded from 0.3 unable to build, and makes update keep the files you changed. The Tailwind CLI is now downloaded once per machine instead of into every project, and the download survives slow connections. It also fixes remove, the dark theme and the package TimePicker.
Tailwind CLI: once per machine
- Projects no longer hold the binary. The standalone Tailwind CLI (about 110 MB) is downloaded once into
~/.shellui/bin(orSHELLUI_CACHE_DIR), andinitand the build run it from there. A new project went from about 112 MB to 130 KB, and later projects set up offline. A copy in a project's.shellui/binstill takes precedence. The binary is a build tool and never ships with your app. - Nothing in
.shellui/is committed: it now contains a.gitignoreof*. - Slow connections work. The download streams to a
.partialfile, resumes after a dropped connection, retries, and only gives up after a minute with no data. The build's own download uses the same cache and retries too. - A failed download no longer stops
init. It finishes the rest of the setup and warns, and the next build tries again; its warning names the URL and where to save the file.
shellui update and remove
updateinstalls new dependencies. Components gain parts between versions; in 0.4,breadcrumbgainedbreadcrumb-list,-link,-page,-separatorand-ellipsis, andtabsgainedtab-models.updateonly rewrote existing files, so a project updated from 0.3 failed to build (BreadcrumbList,TabItemnot found). It now installs missing dependencies the wayadddoes, with their NuGet packages and_Imports.razorusings.updatekeeps your changes.shellui.jsonnow records a hash of each file the CLI writes.updateskips files you have changed since and says so;--forceoverwrites them.removefinds files the way install writes them. It honours a customComponentsPath, removes dashboard and auth layouts, lists files that still use a removed layout (usuallyRoutes.razor), and counts what it removed.
Fixes
- Dark theme: the themes set
color-scheme, so the browser draws its own controls (the<input type="date">calendar, number spinners, scrollbars, autofill,<select>lists) dark on a dark page. - NuGet package
TimePickerthrew aFormatExceptionwheneverValuewas set. It now shows the time. - NuGet package
shellui-theme.cssno longer logs a 404 when linked directly. - NuGet packages have the ShellUI icon and show the logo at the top of their README.
- Everything fixed in 0.3.3 and 0.3.4 is included.
Upgrading from 0.4.0-alpha.1
- CLI: update the tool, then run
shellui update. Files installed by alpha.1 have no recorded hash, so this first update keepsapp-sidebar,sidebar-accountand the dashboard and auth layouts if they differ from the template, and rewrites the other components. Commit first so you can review the changes. From then on, every file you edit is kept. - Tailwind CLI: the same
shellui updatereplacesBuild/ShellUI.targetsif you haven't edited it, adds.shellui/.gitignore, and deletes the project's copy of the Tailwind CLI when it's the same as the shared one. An edited targets file is left alone with a note. - Existing
input.css:updatedoesn't rewrite it. Addcolor-scheme: light;inside:rootandcolor-scheme: dark;inside.dark, or runshellui theme applyagain if you use a tweakcn theme. - NuGet package: update
ShellUI.Componentsto0.4.0-alpha.2.
Upgrading from 0.3: follow the 0.4.0-alpha.1 notes below, then the steps above.
dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.2
dotnet add package ShellUI.Components --version 0.4.0-alpha.2
Full changelog: v0.4.0-alpha.1...v0.4.0-alpha.2
v0.4.0-alpha.1
The first 0.4 prerelease. It adds 14 components, compositional parts for eight existing ones, dashboard and sign-in page blocks, and support for apps that use ASP.NET Core Identity.
Installs need --version 0.4.0-alpha.1. The stable release is still 0.3.2. Report issues on GitHub.
New components
The CLI now has 93 direct targets, up from 76 in 0.3.
| Target | What it is |
|---|---|
kbd |
Keyboard key hint |
aspect-ratio |
Fixed-ratio container |
button-group |
Joined buttons, horizontal or vertical |
toggle-group |
Single- or multi-select toggles |
input-group |
Input with Prefix and Suffix slots |
number-input |
Stepper input with min, max and step |
stat-card |
KPI tile with a trend badge |
timeline |
Vertical event timeline |
tree-view |
Expandable, selectable tree |
qr-code |
QR code rendered as SVG (adds the QRCoder package) |
image-viewer |
Thumbnail with a zoomable lightbox |
chat, chat-message, chat-input |
Chat panel, message bubbles with a streaming indicator, and a prompt input |
Compositional parts
Eight more components can be built from parts, shadcn-style. Each mode is opt-in, so existing markup keeps working, and the parts install with their parent.
- Alert Dialog:
AlertDialogTrigger,Content,Header,Title,Description,Footer,Action,Cancel. Escape acts as Cancel. - Breadcrumb:
BreadcrumbList,Link,Page,Separator,Ellipsis. - Command:
CommandInput,List,Group,CommandOption,Empty,Separator. - Form:
FormField,Item,Label,Control,Description,Message, with live validation inside anEditForm. - Menubar:
MenubarMenu,Trigger,Content,Separator. - Pagination:
PaginationContent,Item,Link,Previous,Next,Ellipsis. - Sheet and Drawer:
Header,Title,Description,Footer,Close. CLI templates use them withCompositional="true".
Blocks and shellui init
- Dashboard setup in
init:initasks for a layout, or takes--dashboard 01|02|none, and wires it in:Routes.razoruses it, the stockMainLayoutandNavMenuare removed when unmodified, the error bar moves toApp.razor, and the sidebar links come from your pages. See the dashboard guide. - Sample pages restyled: unmodified
dotnet new blazorpages get ShellUI's Tailwind classes. Edited pages are listed, not changed. - ASP.NET Core Identity apps: the
/Accountpages render statically while the rest of the app is interactive, the dashboard sidebar shows the sign-in state, and the newauth-01,auth-02andauth-03blocks restyle the sign-in pages. See Authentication. - Tailwind CLI: in projects set up by this version, the build downloads the pinned Tailwind CLI when
.shellui/binhas none, for example after a fresh clone, and warns if it can't. - Terminal:
initshows the ShellUI logo and an animated loader;add,updateand the theme commands use a compact spinner.
Component changes
- Loading is rebuilt with 23 variants, including
logo,snake,wave,typingandshimmer. Its animations ship inside the component, so they also work with the NuGet package. - Command is rewritten: it filters as you type, supports the arrow keys, Home, End and Enter, and has optional group headings. Selecting an item now runs its
CommandItem.Action, then raisesCommandSelected. Command Palette gets the same behavior and a bindableIsOpen. - Dropdown and Popover close on Escape.
Fixes
- The CLI's
SidebarProviderloggedJSDisconnectedExceptiontwice on every page reload. It no longer does. init --tailwind standalone|npmnow skips the Tailwind prompt, and an unknown value fails beforeinitchanges the project.shellui updatecounts updated, skipped and failed components separately.- Everything fixed in 0.3.1 and 0.3.2 is included.
Breaking changes
- Calendar:
SelectedDateChangedis nowEventCallback<DateTime?>, so@bind-SelectedDateworks with aDateTime?field. Handlers that take aDateTimemust take aDateTime?.
Upgrading from 0.3
With the CLI, update the tool, then rewrite the installed components from the new templates:
dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.1
shellui update
update overwrites the files, so commit or back up any components you customized first. Build/ShellUI.targets is only written by init, so projects set up with 0.3 keep the old Tailwind build step.
With the NuGet package:
dotnet add package ShellUI.Components --version 0.4.0-alpha.1
If you handle Calendar.SelectedDateChanged, change the handler's parameter to DateTime?. If a CommandSelected handler runs the item's Action itself, remove that call.