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.1 1 ) Goals / criteria for component review and selection
- 1.2 2 ) UI elements to be replaced or introduced
- 1.3 3 ) Review
  - 1.3.1 3.1. Collapsible left-hand menu
  - 1.3.2 3.2. Breadcrumb
  - 1.3.3 3.3. Table
  - 1.3.4 3.3.1 Data Grid Assessment
  - 1.3.5 3.4. Typography
  - 1.3.6 3.5 Dropdowns/Selects
  - 1.3.7 3.6. Button
  - 1.3.8 3.7. Icons
  - 1.3.9 3.9. Card
  - 1.3.10 4.0. Modal
  - 1.3.11 4.1 Tabs
2 Final Summary

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	Met in DCB-278 and DCB-396. WCAG 2.1.
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

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	https://openlibraryfoundation.atlassian.net/browse/DCB-255
Breadcrumb	Breadcrumb.tsx Header.tsx _header.scss	MUI Breadcrumbs	https://openlibraryfoundation.atlassian.net/browse/DCB-256
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)	https://openlibraryfoundation.atlassian.net/browse/DCB-231
Typography (Headers, titles etc)	Throughout	MUI Typography	https://openlibraryfoundation.atlassian.net/browse/DCB-304
Dropdowns / Selects	HeaderProfileNav.tsx	Replacing dropdown with MUI App Bar	https://openlibraryfoundation.atlassian.net/browse/DCB-278
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)	https://openlibraryfoundation.atlassian.net/browse/DCB-304
Icons	Profile.tsx	React Icons - standard switch from FontAwesome icons currently present (and any others)	https://openlibraryfoundation.atlassian.net/browse/DCB-303
Search	Table.tsx	MUI X Data Grid Quick Filter (Will be implemented as part of the Data Grid)	https://openlibraryfoundation.atlassian.net/browse/DCB-231
Card	Profile.tsx	MUI Card + Paper (to hold cards)	https://openlibraryfoundation.atlassian.net/browse/DCB-304
Modal	Details.tsx AddAgenciesToGroup.tsx agencies/index.tsx groups/index.tsx NewGroup.tsx requests/index.tsx	MUI Modal, Dialog (for things like confirmation).	https://openlibraryfoundation.atlassian.net/browse/DCB-304
Pagination (this refers only to the UI pagination controls)	Table.tsx	MUI x Datagrid With customisation so user can go to Page ‘X’ by clicking on the number / typing it in	https://openlibraryfoundation.atlassian.net/browse/DCB-231

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.	MUI Accordion	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	MUI documentation	Npm react pro sidebar packages page	Npm burger menu package page	N/A
Pros	Included in the MUI package Easy to use	Highly customisable Visually appealing	Includes transition animations Has been around for 8+ years	No package installation needed
Cons	Big package size - but this includes many other components that will be used.	Extra package install	Relatively large package Inactive maintenance	Will take time to implement (another task)
Package size	501.3kB (entire material package) 20.4kb - drawer package	64.2kB	108.3kB
Usage & Maintenance Stats (package score)	95/100	72/100	69/100
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://mui.com/material-ui/react-breadcrumbs/	useMatches \| React Router API Reference
Pros	Comes with the MUI package	Part of the react-router-dom, so can be used along with other routing features Minimal code Popular and well maintained
Cons		The code uses nextjs routing, therefore would have to be reworked to include react-router-dom
Package size	501.3kB (material package) 19.4kB - breadcrumb package	70kB
Usage & Maintenance Stats (package score)	95/100	100/100
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	MUI documentation	Material React Table documentation
Pros	The project already uses TanStack.	Imports TanStack as well as only the necessary components from MUI No need to switch UI components If the project decides to switch from MUI to another UI
Cons	x
Package size	501.3kB (entire material package) 11.3kB - table package	176.9kB
Usage & Maintenance Stats (package score)	95/100	83/100
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

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	MUI Documentation	guide
Pros	Appears to be the most recommended component, as there are a few guides on how to use it here and here	Full control over code (again)
Cons	Nothing notable	Again, will take time
Package size	501.3kB (entire material package) 11.8 kB - Typography
Usage & Maintenance Stats (package score)	95/100	?
Final Choice	x
Justification	It will be easier than coding a new Typography component.

3.5 Dropdowns/Selects

Choices	MUI - Menu Component	React Select	Custom
Notes/Documentation	Documentation linked to title	Documentation linked to title
Pros	No extra import required	More features than MUI for selection features (animation, styles) 5k avg weekly downloads, popular for a smaller package	Complete control of code
Cons	Not as customisable as react-select	Extra import cost	Less features Needs maintaining
Package size	501.3kB (entire material package 23.kB - Menu	90.9kB
Usage & Maintenance Stats (package score)	95/100	78/100	?
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	Documentation from MUI
Pros	Inclusive in MUI (the package we plan to use)	Full control Not reliant on a package
Cons	?	Will take time to implement own button Is the effort necessary?
Package size	501.3kB (entire material package) 17.2kB - Button
Usage & Maintenance Stats (package score)	95/100	?
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	MUI Icons documentation	React Icons page	Font Awesome Page
Pros	Easy to navigate Icons fit a consistent theme When using code examples from MUI, the icons don’t need to be changed	You only need to import icons you will use Fairly lightweight Includes icons from many different place	Icons are ‘fonts’ are easy to manipulate and style Best for performance Support documentation and pro-support (paid only)
Cons	Additional import on top of MUI package	May not all adhere to a consistent design theme as icons are pulled from different websites	Some paid features Pay wall for support features
Package size	4.4MB	6.6kB	56.6kB
Usage & Maintenance Stats (package score)	95/100	90/100	93/100
Final Choice		x
Justification		Small package size and no pay wall for icons

3.9. Card

Choices	MUI Card	react-ui-cards
Notes/Documentation	MUI Documentation	Npm package page
Pros	More customisable	Neat, pre-made cards without having to write much extra code
Cons	Potentially have to write more code to create a nice looking card	Not very popular and a small community (low package rating) Unsure of how customisable it is
Package size	501.3kB 11.8kB - Card	446kB
Usage & Maintenance Stats (package score)	95/100	56/100
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	Documentation	Npm package page
Pros	Already themed (visually pleasing) Seems easy to implement	Highly customisable
Cons	Nothing notable	CSS will need customising as the default modal is not visually pleasing Inactive maintenance
Package size	501.3kB 17.9kB - Modal	186kB
Usage & Maintenance Stats (package score)	95/100	80/100
Final Choice	x
Justification	No notable issues

4.1 Tabs

Choices	MUI Tabs	React-Tabs
Notes/Documentation	Documentation	Website
Pros	No extra import	More options for customising (tabs inside tabs, dynamic tabs) Very small package size
Cons	Simple compared to react-tabs
Package size	501.3kB 16.5kB - Tabs	6.5kB
Usage & Maintenance Stats (package score)	95/100	86/100
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.
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.
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.

DCB Admin App refresh