As you might know, UI Core version 4 has recently been released. We recommend you check out our changelog for the full list of changes. There are also live demos and API docs at https://ui-core.dhis2.nu.
To help you upgrade to ui-core 4 we’ll briefly go through the most important changes that require your attention:
- Form controls look and feel
- Form controls and Field components
- Callback style
- Select component removal
- SingleSelect and MultiSelect components introduced
- TextArea and TextAreaField introduced
- React version requirement changed
- Removal of nested component (
- And more...
There are three main reasons for the breaking change in the input fields:
The previous inputs were not recognizable enough as inputs for all users
There were no good reasons to maintain multiple input styles
The filled and outlined inputs sometimes interchanged the use of labels and/or placeholder text. This needed to be simplified to define clearly the roles of the label and placeholder.
The previous filled and outlined inputs were inherited from our use of Material UI. When building our own UI library we have been able to create an input component that is right for DHIS2 applications. The new input component is:
Recognizable: it looks and behaves like input fields most users are familiar with
Understandable: there are no animations or moving parts to distract from its core use
Using obvious label and placeholder texts: a label is always above, a placeholder text is always within. Using one does not affect the other.
If you haven't already, make sure to remove the
filled prop from your
InputFields, as it no longer does anything.
You'll notice we've mentioned the
InputField above. All of
our form components now have a
<componentname>Field equivalent. The
Field variants add props for commonly used patterns like a
helpText and more. See our API
docs for the complete list.
The callback style for ui-core components has changed. Previously any
callbacks passed to our components would be called with the synthetic
event. We’re now calling all callbacks with an object with relevant data
first, and the synthetic event second. To clarify, this is for example
onChange prop on our
Input component now works:
We’ve done this because ui-core 4 introduced non-native components, and this allows us to pass any custom data besides the event. To keep things consistent, we’ve adopted this pattern for all our components. See our changelog for the exact properties passed in the first argument.
Speaking of non-native components, the
Select component has been
deprecated In favor of the new
components. They’re not backed by the native select element, and thus
allow us to create a select component that is more in line with modern
UI and UX expectations. As a small example, this is how the new
MultiSelect can be used:
We’ve added several other new components, most notably:
There has been a slight bump in the required react version, ui-core now requires at least react 16.8 and react-dom 16.8.
Modalnow always renders (instead of accepting an
openprop). Make sure to not render it if you don't want it to be displayed.
Besides the user-facing changes listed above, we've added a lot of integration tests for our components and are in the process of adding more.
The TabBar no longer has to be nested in a ScrollBar, instead the TabBar now has a
Modal.Titlehave been removed. Instead you can use
classNameprops are allowed on all our components, but note that we do not guarantee that styling component internals won't break, so use with care.
Our theme now also exposes spacers, elevations and layer constants.
We hope the above is useful in your upgrade to version 4 of ui-core. Let us know if you encounter anything, and feel free to open an issue or PR!