This document provides information about breaking changes and their migrations for major versions of Kirby Design System.
- As of version 10 Kirby expects Angular 18.0.0 or later.
The flat property has been removed and all usages of this property must be replaced with the new variant property for identical behavior by inserting variant="flat" instead.
The TableComponent and TableRowComponent have been been removed and should be replaced by the kirby-table CSS class.
The DataTableModule has been deprecated in favor of the standalone TableSortableComponent.
All imports of DataTableModule should be replaced with TableSortableComponent.
DataTableModule will be removed in Kirby v11.
The deprecated customIconName property has been removed and iconName should be used as a direct replacement.
The deprecated customName property has been removed and name should be used as a direct replacement.
The deprecated alertConfig parameter in modalController.showModal and modalController.navigateToModal has been removed and the canDismiss callback should be used as a direct replacement.
The callback can be set on the parent modal from your own embedded component, be provided to the ModalConfig or set directly via the canDismiss input property when using the modal component in your template.
The experimental ModalV2 module including the ModalV2Controller and <kirby-modal-v2> component have been removed. All features have been ported back to the existing Modal module and should be used instead.
The following options for the maxWidth property have been removed and usages should be updated accordingly:
standard: remove all usages (same as default width of page)optimized: should be replaced withlg
The deprecated page-local-navigation component has been fully removed and should be replaced by kirby-tab-navigation.
The deprecated $page-content-max-width Sass variable has been removed and $page-content-max-width-default should be used as a direct replacement.
The deprecated routerLink property in kirby-tab-button component has been removed and tab should be used as a direct replacement.
The shadow input binding has been removed and stroke should be used instead for a similar effect.
The deprecated attention level 4 has been removed. This has no visual significance as level 4 was mapped to level 3 internally in the button, but any references to attention level 4 should be removed from code.
KirbyBadgeModule has been removed. BadgeComponent is now standalone and can be imported directly.
The Experimental Alert has been fully removed and we recommend to use the normal alert instead.
The grid component has been removed in favor of using the much more flexible Grid HTML classes.
The following methods have been removed from the modalController and all usages of these methods should be removed: registerPresentingElement, scrollToTop, scrollToBottom.
The change event no longer emits for each value change, but instead only when the user releases the knob after dragging or when the user moves the knob with keyboard arrows.
This prevents excessively emitting a lot of events especially for large ranges, and removes the need for debouncing measures in applications.
If the previous functionality of reacting to each value change is needed consider binding to the move event instead.
Navigation arrows (desktop only) and selected slide indicators are now shown by default. It is possible to opt-out of this by setting showNavigation to false.
The selectedSlide event emitter has been removed and slideChange should be used as a direct replacement.
A new xsmall breakpoint (320px) has been introduced in the $breakpoints map exposed by Kirby. The xsmall breakpoint replaces the old small breakpoint, which is now 632px.
A $page-content-max-widths map has been introduced to support default, optimized and full-width content on Kirby Page. This means that the standalone variable $page-content-max-width is deprecated in v9 and $page-content-max-width-default should be used in its place.
For backwards compatability both variables return the default value until v10 where $page-content-max-width is removed entirely in favor of $page-content-max-width-default.
Values from the new content-width map can be retrieved with the get-page-content-max-width() convenience function, e.g. get-page-content-max-width('full').
The @kirbydesign/core package that contain helpers for the designsystem package is now an ES Module, and no longer exports a CommonJS javascript bundle. If e.g. your Jest tests are otherwise configured to use CommonJS you might need to ignore transformation of the @kirbydesign/core files.
As of Kirby version 8.3.0 a number of enhancements have been introduced, improving the look and feel of components like Page and Modal while also providing a better user experience on larger screen sizes (e.g. desktop).
As these features are direct replacements of existing functionality, the existing functionality will be marked as deprecated from v9, and finally removed in v10. To gain the benefit of the improvements we strongly encourage consumers to migrate to the new features as soon as possible.
Menu replaces Action Sheet to provide a better experience across platforms and screen sizes. Menu is a new component that renders a button that acts as a trigger for showing / hiding a popover menu. The menu is used declaratively in markup to simplify usage and is no longer instantiated through the modalController like the Action Sheet.
Use of custom page elements for title, subtitle, action buttons and fixed content with the *kirbyPage-directives are being superseeded by the new kirby-header component. See the Header documentation for more information on how to integrate this into your page.
The content area in Page now defaults to a max width of 720px to improve desktop support with optional presets to adjust the content width. See the “Content Width” section in Kirby Page Docs for more details.
Kirby page can also be used together with a set of new css utilities that allow further customisation for larger screen layouts. Use Kirby Grid to implement responsive layouts. For more details and examples of usage see Kirby Grid Docs.
The experimental kirby-page-local-navigation component is deprecated and replaced with the functionally equivalent kirby-tab-navigation component.
The tab text is now declared by setting the ‘label’ attribute of the kirby-tab-navigation-item.
The optional right-justified badge is declared by specifying a kirby-badge element within the kirby-tab-navigation-item.
- As of version 8, Kirby expects Angular 15.0.0 or later versions.
- ChartJS, RxJS and date-fns related packages are now peerDependencies, and should be installed by projects.
- Kirby now relies on features in RxJS 7, and consumers should update the dependency accordingly.
- ResizeObserver and IntersectionObserver polyfills have been removed.
- If they have previously been copied from the Kirby package to your projects output folder compile time via
build > options > assetsin angular.json that configuration should be removed, as Kirby no longer supplies the polyfills.
- If they have previously been copied from the Kirby package to your projects output folder compile time via
Additionally, multiple components and directives are now standalone components, which means they should be imported rather than declared inside consuming angular components. Expand below to see a list of all related components.
Expand to see full list of new standalone components
- AvatarComponent
- ActionSheetComponent
- AlertComponent
- AffixDirective
- ButtonComponent
- CalendarComponent
- CheckboxComponent
- DividerComponent
- FabSheetComponent
- FlagComponent
- DateInputDirective
- DecimalMaskDirective
- InputComponent
- TextAreaComponent
- GridComponent
- ItemGroupComponent
- ItemSlidingComponent
- LoadingOverlayComponent
- ModalFooterComponent
- ModalWrapperComponent
- ModalCompactWrapperComponent
- FitHeadingDirective
- PopoverComponent
- ProgressCircleRingComponent
- ProgressCircleComponent
- RangeComponent
- ReorderListComponent
- SectionHeaderComponent
- ComponentLoaderDirective
- ThemeColorDirective
- SlideButtonComponent
- PageLocalNavigationComponent
- SegmentedControlComponent
- ToggleComponent
The isDestructive behavior of button should only be used internally by Kirby in the alert, as destructive actions are always announced via an alert. Use the default button attention levels and combine with alerts when needed.
A note on button colors: Attention level 3 has changed from an outline button to a white background.
The mode input is replaced with a boolean input 'flat' that can be set to true to remove the shadow around the card. This is not intended for use together with a clickable card or a card with a disclosure indicator.
The 'highlighted' look that could previously be set on cards is no longer an option and all cards will now have the same shadow going forward.
The hasDarkBackgroundColor input of card is no longer available. To have similar functionality themeColor="dark" should be set on cards instead, so interaction states light up instead of getting darker. The option is also useful for background images with darker content, because it ensures a better fallback color if the image loads asynchronosly.
Some of the Chart.js types previously re-exported by Kirby should now be imported directly from Chart.js.
Before:
import { ChartOptions, ChartEvent, ActiveElement, Chart, AnnotationOptions } from '@kirbydesign/designsystem';
After:
import { ChartOptions, ChartEvent, ActiveElement, Chart } from 'chart.js';
import { AnnotationOptions } from 'chartjs-plugin-annotation';
A new disclosure indicator feature has been added (e.g. an arrow on list items indicating a navigation option). See the Item and Card documentation on the cookbook for implementation details. While not a breaking change, it is an important update to the affordance of the list and items. The UI guidelines are as follows:
Components where disclosure indicators should be added
Disclosure Indicators are shown on all list items and cards that are clickable and navigate to a new page, drawer or modal - both navigation items and actions items.
Non-clickable items that only shows details does not have disclosure indicators and should preferably use the XS item with key + title (fx card details).
OBS: Generally avoid having both clickable and non-clickable items in the same list. In such case a light or semi dark title can be used to signify that the item is non-clickable.
Related components without indicators
Sidebar menu items only has disclosure icons if the item is expandable with sub-levels.
Banner cards with images or illustrations should not have disclosure indicators. The image or illustration or the button is the signifier for affordance.
While not a breaking change, attention levels for dropdowns have changed quite dramatically to match buttons attention level designs. This means that attention level 2 buttons are now black, and if a white dropdown is desired, attention level 3 should be used instead.
It is now required to pass [selectable]="true" to kirby-item if items in the list should have a hover effect.
When setting value on Range the value change event is no longer fired. It will only be triggered if the user has interacted with the range slider.
From v6 and onwards, Kirby no longer supports Angular projects using the Legacy View Engine. Applications already using Ivy should see no differences other than Kirby not needing an additional compile-step on their side via ngcc.
global-styles and utils are now the only modules that can be loaded from ~@kirbydesign/designsystem/scss.
This means that modules like ~@kirbydesign/designsystem/scss/theme/colors is no longer available as a standalone module, and should instead be changed to ~@kirbydesign/designsystem/scss/utils,
which forwards all mixins and functions exposed by Kirby.
okBtnText and cancelBtnText of AlertConfig are removed, and the existing okBtn and cancelBtn should be used instead, as a direct replacement for these.
The kirby-chart input property dataLabels has been removed. Use labels (with a similar API) instead.
Use of IconSettings is deprecated, use IconRegistryService instead, as per the icon documentation, as follows:
import { IconRegistryService } from '@kirbydesign/designsystem';
const customIcons = [
{
name: 'customIconName',
svg: '[PATH_TO_SVG_FILE]',
},
...
];
@NgModule({ ... } )
export class MyModule {
constructor(iconRegistryService: IconRegistryService) {
iconRegistryService.addIcons(customIcons);
}
}
*kirbyListItem and *kirbyListFlexItem is replaced in favor of the *kirbyListItemTemplate directive.
The dim field of the ModalConfig interface has been removed.
The title field of the ModalConfig interface has been removed. Instead, you should include a <kirby-page-title> element inside the embedded component markup with the title of your modal.
<kirby-page-title>My Modal Title</kirby-page-title>
<p>Some content of the embedded component</p>
See the modal documentation for more examples of this.
The current spacing below custom titles (title elements with the *kirbyPageTitle directive) has been removed.
In cases where a text block immediately following the title heading within a custom title element has lost its intended spacing, the text should be moved to the new custom subtitle element (*kirbyPageSubtitle).
It is no longer an option to mark a SegmentItem as checked when provided in the items input of SegmentedControl.
Use selectedIndex or value on <kirby-segmented-control> instead.
The danger variant of MessageType has been removed. Use Kirby Alert for critical events instead.
To improve the general performance of Kirby components, OnPush change detection has been enabled on a lot of the simpler components.
This is not a breaking change, as it has only been carried out for components that should be robust to this change because they have immutable inputs. Even though it has been tested thoroughly there might be edge cases or unforeseen consequences related to this change so please be aware that the following components now utilise OnPush change detection:
kirby-appkirby-buttonkirby-card-headerkirby-card-footerkirby-chipkirby-dividerkirby-empty-statekirby-fab-sheetkirby-iconkirby-item-componentkirby-list-experimentalkirby-list-headerkirby-list-section-headerkirby-loading-overlaykirby-alertkirby-modal-footerkirby-page-footerkirby-radiokirby-rangekirby-router-outletkirby-section-headerkirby-spinnerkirby-toggle