mui-sidebar
v1.0.1
Published
MUI-Sidebar is a fully responsive and customizable sidebar component built with Material UI 5. This library provides an easy-to-use solution for integrating side navigation into your React applications, whether you're targeting small screens, large screen
Downloads
73
Readme
mui-sidebar
Overview
The mui-sidebar
is a versatile, responsive sidebar component built using Material UI 5. It provides a seamless user experience (UX) on both small and large screens, ensuring that your application's layout remains consistent across different devices.
The primary goal of this library is to enhance the UX of sidebar responsiveness rather than just offering a UI component. While this project is currently tailored for personal use, contributions and feature requests are welcome. If you need additional features, please create an issue, and I'll address it as soon as possible.
Example Layouts
Here are some example layouts demonstrating the responsive behavior of the mui-sidebar
:
Small and Large Screen (Sidebar Closed):
Small Screen (Sidebar Opened):
Large Screen (Sidebar Opened)
Installation
To install the mui-sidebar
library, you can use npm. Run the following command in your project directory:
npm install mui-sidebar
This will add mui-sidebar
(https://www.npmjs.com/package/mui-sidebar) to your project's dependencies, allowing you to easily integrate it into your React application.
Available Components
The MUISidebar
library includes several key components that allow for easy integration and customization within your application:
Essential Components
<Sidebar>
The main container for the sidebar. It manages the display and behavior of the sidebar across various screen sizes, automatically adjusting for optimal user experience.<OuterContainer>
The container for the main content of your application, excluding the sidebar. This component helps manage the layout outside of the sidebar.<ContextProvider>
The context provider that is essential for the sidebar's functionality. It manages the state of the sidebar and makes it accessible to the rest of the components.
Tool
useSidebarContext
A custom hook that provides utilities to enhance the sidebar's UX. This hook offers easy access to sidebar-related functions, enabling further customization and extension of the sidebar’s behavior.
Optional Components
<ButtonOpen>
A button component that opens the sidebar. This button can be used out of the box or customized according to your design needs.<ButtonClose>
A button component that closes the sidebar. This button is typically placed within the sidebar for easy access by users.<ListItem>
A list item component designed for elements within the sidebar. It is ideal for navigation links or other list-based content.
Sidebar Component
The <Sidebar>
component is capable of rendering either a Drawer
or SwipeableDrawer
depending on the screen size and user interaction. It intelligently adjusts its mode and appearance based on the device, ensuring a consistent and responsive layout.
useSidebarContext
Properties
The useSidebarContext
hook provides a set of properties and functions to manage the state and behavior of the mui-sidebar
. Below is a detailed explanation of each property:
navigationDrawerWidth: number
Defines the current width of the sidebar (drawer) in pixels. This value can be dynamically adjusted based on the screen size or user preferences.outerContainerWidth: number
Specifies the width of the main content area (outside the sidebar) in pixels. This value helps in calculating the overall layout of the application, ensuring that the sidebar and the main content area are properly aligned.setNavigationDrawerWidth: React.Dispatch<React.SetStateAction<number>>
A function used to update the width of the sidebar. You can call this function with a new width value to resize the sidebar programmatically. ThesetState
function signature ensures that you can pass either a new width directly or a function to calculate it based on the previous state.isOpen: boolean
A boolean value indicating whether the sidebar is currently open (true
) or closed (false
). This state can be used to conditionally render components or trigger animations based on the sidebar's visibility.isLargeScreen: boolean
A boolean value that identifies if the current screen size is considered "large" according to the responsive breakpoints set in the application. This property is useful for adjusting the sidebar's behavior, such as keeping it permanently open on large screens.toggleDrawer: (open: boolean) => (event: React.KeyboardEvent | React.MouseEvent) => void
A function to toggle the sidebar open or closed. This function accepts a boolean (open
) that determines the desired state of the sidebar. It returns another function that handles the triggering event, which can be either a keyboard or mouse event. This setup allows for flexible and accessible control of the sidebar, ensuring that it can be toggled through various user interactions.
Usage Example
Here's a simplified example of how to use the mui-sidebar
components within your application.
SidebarMenu Component
The SidebarMenu
component represents the contents of the sidebar. It includes the following key elements:
Context Access: The component uses the
useSidebarContext
hook to access the current state of the sidebar, particularly whether the screen is large or small. This allows for conditional rendering based on screen size.Structure:
- A
Toolbar
that holds a title ("I don't know Rick") and a close button (Sidebar.ButtonClose
) that only appears on smaller screens. - A
List
that containsSidebar.ListItem
components, each representing a navigational item in the sidebar. These items include a URL, text, subtitle, and an icon.
- A
This component is designed to be flexible and easily customizable, allowing you to replace the list items, change the icons, or modify the structure to fit your application's needs.
export const SidebarMenu: React.FC = () => {
const { isLargeScreen } = Sidebar.useSidebarContext();
return (
<Sidebar>
<Toolbar>
<Stack
direction={"row"}
justifyContent={"space-between"}
style={{ width: "100%" }}
>
<Typography>I don't know Rick</Typography>
{!isLargeScreen && <Sidebar.ButtonClose />}
</Stack>
</Toolbar>
<Divider />
<List component="nav">
<Sidebar.ListItem
url="/visit-lobezno"
text="Lobezno"
subtitle="Be carefull so strong..."
icon={<Difference />}
/>
<Sidebar.ListItem
url="/visit-deadpool"
text="Deadpool"
subtitle="Be carefull so rude..."
icon={<CollectionsBookmark />}
/>
</List>
</Sidebar>
);
};
export default SidebarMenu;
Root Page
The Root
component represents the main structure of your application. It sets up the context for the mui-sidebar
and defines the layout outside of the sidebar.
Context Provider: The
Sidebar.ContextProvider
component wraps the entire application. It initializes the sidebar settings, such as whether the sidebar is initially open or closed on large screens. This context provider is crucial for managing the state and behavior of the sidebar throughout your application.Layout Structure:
- The
HeaderBar
component is included to display the app's header. - The
Sidebar.OuterContainer
wraps the main content of your application that resides outside the sidebar, ensuring that the layout adjusts correctly depending on the sidebar's state.
- The
This structure provides a clear separation of concerns, making it easy to manage the sidebar and the rest of the application's layout independently.
<Sidebar.ContextProvider largeScreenSettings={{initalOpen: false}}>
<HeaderBar />
<Sidebar.OuterContainer>
area outside the sidebar
</Sidebar.OuterContainer>
</Sidebar.ContextProvider>
AppBar Component (HeaderBar)
The HeaderBar
component is a fixed app bar that serves as the top navigation or header for your application. It interacts with the MUISidebar
and contains the following features:
Context Access: Similar to the
SidebarMenu
, this component uses theuseSidebarContext
hook to determine whether the sidebar is open or closed and to identify the screen size.Responsive Interaction:
- When the sidebar is closed, a button (
Sidebar.ButtonOpen
) is displayed to allow users to open the sidebar. - When the sidebar is open, a close button (
Sidebar.ButtonClose
) is displayed for easy closure.
- When the sidebar is closed, a button (
Header Content:
- The
AppBar
includes aToolbar
with a title ("Hello") centered within it, ensuring a clean and organized header.
- The
This component demonstrates how to integrate the sidebar controls directly into the app's header
...
const { isLargeScreen, isOpen } = Sidebar.useSidebarContext();
...
<AppBar position="fixed">
<Sidebar.OuterContainer>
<Toolbar>
{ !isOpen && <Sidebar.ButtonOpen /> }
{ isOpen && <Sidebar.ButtonClose /> }
<Box sx={{ width: "100%" }}>
<Typography
variant="h6"
component="h1"
>
hello
</Typography>
</Box>
</Toolbar>
</Sidebar.OuterContainer>
</AppBar>
<SidebarMenu />
Summary
These examples together illustrate how to set up a responsive sidebar in a React application using the mui-sidebar
library. The SidebarMenu
defines the contents of the sidebar, the Root
component sets up the overall layout and context, and the HeaderBar
integrates sidebar controls into the app's header. By following this structure, you can create a responsive and intuitive sidebar experience that adapts to different screen sizes and user interactions.
Roadmap
The following is a roadmap outlining the future objectives for the mui-sidebar
library. Please note that while these features are planned, this project is not my primary focus, so there may be some delays in their implementation. However, contributions and feedback are always welcome!
Planned Features and Improvements
- Expand Sidebar Flow Support
Enhance themui-sidebar
to support all sidebar flows available in Material UI 5. This will ensure full compatibility and provide users with a wider range of options for sidebar behavior and interaction. - Enhance UI Elements (The optional components)
Improve the optional UI elements provided by themui-sidebar
library, such as buttons and list items. This could include refining styles, adding customization options, and ensuring consistency with Material UI design principles.
Contributions and Timeline
Given that this is a side project, the timeline for these features is flexible. If there are specific features or improvements you would like to see prioritized, please feel free to open an issue or submit a pull request. Your input can help shape the future development of the library!