...
| Table of Contents |
|---|
1 ) Goals / criteria for component review and selection
...
Element | Where’s it used currently? | What are we going to replace it with? | JIRA Ticket |
|---|---|---|---|
Collapsible left-hand menu | SidebarNav.tsx Sidebar.tsx Globals.scss _sidebar.scss | MUI Drawer | |
Breadcrumb | Breadcrumb.tsx Header.tsx _header.scss | MUI Breadcrumbs | |
Table | Bootstrap Table Table.tsx @tanstack/react-table Table.tsx useResource.ts agencies/index.tsx hostlms/index.tsx locations/index.tsx requests/index.tsx Table component Details.tsx components/Table/index.ts agencies/index.tsx hostlms/index.tsx locations/index.tsx requests/index.tsx | MUI X Data Grid (see 3.3.1) | |
Typography (Headers, titles etc) | Throughout | MUI Typography | |
Dropdowns / Selects | HeaderProfileNav.tsx | Replacing dropdown with MUI App Bar | |
Button | Details.tsx Header.tsx Sidebar.tsx SideBar.nav Groups Hostlms Locations Requests login | MUI Button - one primary button per page (as rule - occasional exceptions may be necessary) | |
Icons | Profile.tsx | React Icons - standard switch from FontAwesome icons currently present (and any others) | |
Search | Table.tsx | MUI X Data Grid Quick Filter (Will be implemented as part of the Data Grid) | |
Card | Profile.tsx | MUI Card + Paper (to hold cards) | |
Modal | Details.tsx AddAgenciesToGroup.tsx agencies/index.tsx groups/index.tsx NewGroup.tsx requests/index.tsx | MUI Modal, Dialog (for things like confirmation). | |
Pagination (this refers only to the UI pagination controls) | Table.tsx | With customisation so user can go to Page ‘X’ by clicking on the number / typing it in |
Possible Future Components (to be implemented in those tickets)
Tabs | Not yet used but will be needed for different data views. | MUI Tabs | Future ticket when needed |
Accordion | Not yet used but will be needed for record views. | Future ticket when needed |
3 ) Review
Components have been selected from Material design libraries and evaluated against the goals (see section 1) for their suitability for use in the Admin app.
3.1. Collapsible left-hand menu
Choices | MUI - React Drawer | react-pro-sidebar | react-burger-menu | Custom |
Notes/Documentation | N/A | |||
Pros |
|
|
|
|
Cons |
|
|
|
|
Package size | 501.3kB (entire material package) 20.4kb - drawer package | |||
Usage & Maintenance Stats (package score) | ||||
Final Choice | x | |||
Justification | Included in the MUI package that is planned to be used, making it convenient. |
3.2. Breadcrumb
Choices | MUI - Breadcrumbs | react-router-dom |
Notes/Documentation | https://reactrouter.com/en/main/hooks/use-matches#breadcrumbs | |
Pros |
|
|
Cons |
| |
Package size | 501.3kB (material package) 19.4kB - breadcrumb package | |
Usage & Maintenance Stats (package score) | ||
Final Choice | x | |
Justification | Included in the MUI package and there is no need to rework routing from next js to use it. |
3.3. Table
Choices | MUI - React Table | Material React Table |
Notes/Documentation | ||
Pros |
|
|
Cons | x | |
Package size | 501.3kB (entire material package) 11.3kB - table package | |
Usage & Maintenance Stats (package score) | ||
Final Choice | x | |
Justification | The project already uses TanStack so there is no current need to import a library that imports TanStack again |
3.3.1 Data Grid Assessment
...
Sorting columns
Searching
Filtering
Clicking on rows to reveal details (as opposed to one column being a ‘link’)
Checkbox select
Menu for future bulk actions
3.4. Typography
Choices | MUI - Typography | Custom Typography component |
Notes/Documentation | ||
Pros |
| |
Cons | Nothing notable |
|
Package size | 501.3kB (entire material package) 11.8 kB - Typography | |
Usage & Maintenance Stats (package score) | ? | |
Final Choice | x | |
Justification | It will be easier than coding a new Typography component. |
3.5 Dropdowns/Selects
Choices | Custom | ||
Notes/Documentation | Documentation linked to title | Documentation linked to title | |
Pros |
|
|
|
Cons |
|
|
|
Package size | 501.3kB (entire material package 23.kB - Menu | ||
Usage & Maintenance Stats (package score) | ? | ||
Final Choice | x | ||
Justification | Unless we need the specified features of react-select, there is no need to use it yet. |
3.6. Button
Choices | MUI - Button Component | Custom |
Notes/Documentation | ||
Pros |
|
|
Cons | ? |
|
Package size | 501.3kB (entire material package) 17.2kB - Button | |
Usage & Maintenance Stats (package score) | ? | |
Final Choice | x | |
Justification | Searching around, there seem to be no good single package replacements for the MUI button. It is possible to use a button from another package, however the MUI one is already included in the package the project plans to use |
3.7. Icons
Choices | MUI Icons | React Icons | Font Awesome |
Notes/Documentation | |||
Pros |
|
|
|
Cons |
|
|
|
Package size | |||
Usage & Maintenance Stats (package score) | |||
Final Choice | x | ||
Justification | Small package size and no pay wall for icons |
3.9. Card
Choices | MUI Card | react-ui-cards |
Notes/Documentation | ||
Pros |
|
|
Cons |
|
|
Package size | 11.8kB - Card | |
Usage & Maintenance Stats (package score) | ||
Final Choice | x | |
Justification | The package size for react-ui-cards is quite large |
4.0. Modal
Choices | MUI - Modal Component | react-modal |
Notes/Documentation | ||
Pros |
|
|
Cons |
|
|
Package size | 17.9kB - Modal | |
Usage & Maintenance Stats (package score) | ||
Final Choice | x | |
Justification | No notable issues |
4.1 Tabs
Choices | MUI Tabs | React-Tabs |
Notes/Documentation | ||
Pros |
|
|
Cons |
| |
Package size | 16.5kB - Tabs | |
Usage & Maintenance Stats (package score) | ||
Final Choice | x | |
Justification | This is just a suggestion as tabs are already included in the MUI package, but if more features are needed I would recommend switching over to react-tabs. |
Final Summary
The Material UI switchover was completed in DCB-306, with the work captured in DCB-278 and the results can be viewed at https://admin.dev.resharedcb.org/ . The key improvements this work has delivered have been captured below.
UI components trusted by the very top companies: companies such as Spotify, Netflix and Amazon either use or build on top of MUI, and they’re not alone. Material UI has the largest UI community in the React ecosystem and is one of its leading libraries.
First-class user experience: MUI components are tried, tested and heavily customisable. We’re already customising components such as DataGrids in this release, and as we need more and more functionality our UI will evolve further to meet the needs of our users.
First-class design: MUI is simply more visually appealing than its predecessor, giving our admin UI a bit of ‘sparkle’ and ‘wow’ factor that makes it easier to sell to customers and more enjoyable to use. Our implementation in the admin UI also has the potential to be extended, reused and developed in future K-Int projects, giving us a big headstart on creating a fantastic UI in those projects.
World-class documentation: available at MUI, this documentation provides a massive range of examples and use cases for each component, helping not just with implementation but also with teaching and onboarding. Documentation also helps us fix issues quicker.
Faster navigation: switching to MUI has delivered speed and reliability improvements over react-bootstrap, its predecessor. It also means we can take advantage of Next.js features like server-side rendering, and eventually server-side pagination, so that we can stay fast even when dealing with huge data sets.
Building for the future: Switching to components like MUI Data Grids now means that our UI will stay fast even when dealing with massive data, as these components are designed to work with potentially millions of items.
Smaller bundle size, faster builds: by performing this work, we’ve been able to nearly halve build time by eliminating unnecessary components, npm packages and CSS, streamlining the application and its dependencies.
Easier customisation: our user interface can now be customised either at component-level with just a few lines, or globally with themes, eliminating the need for multiple hard to track changes across lots of CSS files. MUI gives us the power to create beautiful, customisable UIs that can be easily changed for each client’s specific needs.
More features: just by switching to Material, we gained: improved pagination, the ability to search data grids, sort and filter columns, and dark mode, to mention a few.
More accessible: now fully compliant with WCAG 2.1, the admin UI is hugely accessible after the Material UI upgrade, with more accessibility improvements coming in future releases and the AXE Dev Tools being used to keep it accessible going forward. This also provides an accessibility template to build on in future K-Int releases/projects.
Supports internationalisation: although we’ve not implemented this yet, just switching to Material UI makes supporting different locales a lot easier, with just a few lines of code required.
Easier to test: MUI components have well-known and well-documented established behaviours, making them easier to test when we implement automated testing in the UI.
Comes with its own design kits: https://mui.com/design-kits/ - this improves cross-team collaboration between developers and designers and establishes clear design guidelines.
Helps us ship faster: with a huge library of components that can be built upon and combined to fit almost any UI need, there’s no longer a need to ‘reinvent the wheel’ and spend lots of time building components that already exist, freeing up our developers to tackle the bigger problems.