Please note: this is an archived copy. For the most up to date version see https://docs.google.com/document/d/1PviXkmbkl3Q-2Ygvhgw2nzqeL273cpaCDvlyK-ShEs0/edit?usp=sharing
The existing Admin app needs evaluating with a view to replacing components to fix issues with non compliance against accessibility guidelines, and to enable better development in the long term.
Material UI comprises a more complete set of components which are known to be needed now or anticipated in the future.
This document supports the DCB Jira ticket:
1 ) Goals / criteria for component review and selection
Goal | Description | Priority | Notes |
Skinnable UI | The visual presentation needs to be re-skinnable, to support different branding requirements for organisations | Very high | Theme/template styling will be applied once the components are switched over. DCB-312 provides the basis for this functionality. |
Internationalisation | The app needs to be translatable into unlimited languages | High | To be continued in https://openlibraryfoundation.atlassian.net/browse/DCB-285 |
Accessibility | WAI AA must be supported as a minimum | Very high | |
Open Source | Needs to be free to use | Very high | Met: MUI is an open source library and ‘free forever’ under the MIT licence. |
Use | Needs a healthy user and developer community | High | Met: MUI is one of the most used UI libraries in the world with an active community and regular maintenance. |
Maintenance | Needs to be regularly maintained | Very high | See above. |
Responsiveness | Support for tablets and wider screens. Support for mobiles is desirable but not as important | High | Met, with mobile support to be potentially added in future. |
2 ) UI elements to be replaced or introduced
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.tsx Header.tsx _header.scss | MUI Breadcrumbs | ||
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) | ||
Throughout | MUI Typography | ||
HeaderProfileNav.tsx | Replacing dropdown with MUI App Bar | ||
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) | ||
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) | |
Profile.tsx | MUI Card + Paper (to hold cards) | ||
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)
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 | ||
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
When considering a replacement for the Table component, a new alternative became apparent in the form of MUI X Data Grids. These grids are faster, more efficient at displaying large data sets, and are also more fully-featured than either of the Table components, coming equipped with native pagination, row selection, sortable columns, filtering, and searching, amongst other useful functionality. My initial assumption was that we would have to switch to Tables first due to the format of our data - however, initial investigative work revealed that this would not be necessary, greatly reducing the complexity and time needed to implement this change. As such, MUI X Data Grids became the clear choice to replace Tables in our admin UI application.
Additional note: MUI X Data Grids replace both our Table UI implementation (previously react-bootstrap) and the headless Table logic implementation (Tanstack’s react-table). This makes them significantly more efficient than the other options, as they are effectively ‘two for the price of one’ in our situation.
Key affordances
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.