has been released! Read the upgrade guide

Migrating to v3

This guide will show you how to upgrade your codebase.

1Package upgrade

1yarn upgrade @defencedigital/react-component-library


1yarn upgrade @defencedigital/design-tokens
2yarn upgrade @defencedigital/eslint-config-react
3yarn upgrade @defencedigital/fonts
4yarn upgrade @defencedigital/icon-library

2Breaking changes



  • Use Autocomplete instead of Select for behaviour when the user could type and select an item


  • Replace initials by using children


  • Remove use of color

  • Use COMPONENT_SIZE for size

  • Use BUTTON_VARIANT.DANGER for variant instead of color={BUTTON_COLOR.DANGER}


  • Use checked instead of isChecked

  • Remove use of isValid


  • Use Checkbox instead of CheckboxEnhanced


  • Remove position as component is positioned based on available screen real estate

  • Update onHide callback parameters

  • Update onShow callback parameters


  • Use the replacement DescriptionList


  • Use Placement from @popperjs for placement

  • Use initialIsOpen instead of isOpen

  • Use startDate and endDate instead of value

  • If startDate and endDate are used, these should now be set from the current form state instead of the initial form values. Alternatively, you can use initialStartDate and initialEndDate to only set the initial values

  • onChange is now called when an invalid or disabled date is typed. You should ensure these are correctly handled in your form validation logic

  • The calendar no longer automatically opens when the input is focused. This may affect automated tests 

  • Check presentation as external margins have been removed

  • Remove use of isValid


  • Use instead of DataList

  • Use description instead of title on DescriptionList

  • Use title instead of description on DescriptionListItem

  • Check presentation as external margins have been removed


  • Rename to DismissibleBanner from DismissableBanner


  • Update onSearch callback parameters


  • Remove use of canClear

  • Use size={COMPONENT_SIZE.SMALL} instead of isCondensed

  • Update onChange callback parameters

  • Use icon or prefix instead of startAdornment

  • Use suffix instead of unit

  • Use prefix or suffix instead of unitPosition

  • Check presentation as external margins have been removed

  • Remove use of isValid


  • Update onChange callback parameters


  • Use defaultChecked instead of isChecked

  • Remove use of isValid


  • Use Radio instead of RadioEnhanced


Some of the behaviours associated with this component have fundamentally changed. Refer to the design specification.


  • Replace instances with Autocomplete where autocomplete/typeahead behaviour is required

  • Remove use of isClearable as the clear button is always presented when an item is selected

  • Specify children using SelectOption rather than an array of value and label options

  • Update onChange callback parameters to use value: string | null rather than event: any

  • Remove use of isValid


  • There is the ability to use the Sidebar within a layout by using SidebarWrapper

  • As the component is more composable nav is no longer a prop.

Refer to Storybook for code examples.


  • Specify children using SwitchOption rather than an array of value and label options

  • Use COMPONENT_SIZE for size

  • Remove use of isValid


  • Use TabSetItem instead of Tab

  • Update parameters for use of onChange callback

  • A ResizeObserver polyfill is required in older browsers and in Jest. The CRA template has been updated to reflect this


  • Remove use of footnote in favour of using the component in conjunction with Field and hintText.

  • Remove use of isValid


  • Add a label

  • Remove use of placeholder

  • Check presentation as external margins have been removed

  • Remove use of footnote in favour of using the component in conjunction with Field and hintText.

  • Remove use of isValid


  • Replace render callback with prop bag in TimelineDay, TimelineDays, TimelineEvent, TimelineHour, TimelineHours, TimelineMonth, TimelineMonths, TimelineRow, TimelineRows, TimelineTodayMarker, TimelineWeek, TimelineWeeks

  • Use the hasSide prop instead of TimelineSide 

  • Rename use of renderColumns to render on TimelineRows

  • Remove use of dayWidth and daysTotal in render callback of TimelineWeeks

  • Remove use of isAfterEnd and isBeforeStart in useTimelinePosition in favour of startsAfterEnd and startsAfterStart

Strict null checks

strictNullChecks has been enabled. Interfaces are now more accurate about whether props accept null or undefined. There are no changes required by consumers.

Root font size

  • Root font-size breakpoints have been removed so any workarounds to fix this can be safely removed.

  • To fix a problem with the inconsistent position of bold font compared to other weights, fonts are no longer being loaded from Google CDN. It is worth checking text presentation, in particular where different weights are being used.


Use Field, Fieldset and SectionDivider to replace withFormik and FormikGroup

Icons (legacy icons are gone)

  • Replace dependency on legacy icons with @defencedigital/icon-library equivalent

Legacy icons that have been removed:

  • Bell

  • Graph

  • House

  • Logo

  • RightArrow

  • Search

  • Tools

  • Visibility

  • VisibilityOff

Design Tokens

  • Use ColorGroup instead of ColourGroup

Eslint config

eslint-config-airbnb has been upgraded. The new version includes official compatibility with ESLint 8, drops support for ESLint 6 and older and adds a few new rules.

List of rule changes:

react/function-component-definition has been turned off.

CSS Framework

There is not a 3.x.x of @defencedigital/css-framework and it is strongly recommended to remove any dependencies on this legacy framework. If a dependency is still required then use 2.x.x of @defencedigital/css-framework.

The root of your application should now be wrapped with a single instance of the provided GlobalStyleProvider context provider. (GlobalStyleProvider applies various global styles, and as such, only one instance of it should be mounted at once.)


The MOD.UK Design System provides guidance and tools for building high–quality Services within the UK Ministry of Defence. This project is open source and its source code is available on GitHub.

All content is available under the Apache 2.0 licence, except where otherwise stated.

© Crown copyright