sidebar/introduction
Quick Demo
Definition
Quick Start
Make sure you fully get first! Otherwise, you might get lost reading this, as it uses concepts explained there.
Our sidebar component has 3 family members:
<SidebarLayout>- Usually contains exactly 2 children:
<Sidebar>and<SidebarPeer>. - Handles the core logic of the "sidebar context".
- Usually contains exactly 2 children:
<Sidebar>- High-level view: Think of it as just a card within the sidebar context. Nothing fancy.
- Since it's just a card, put whatever you want inside. No limits.
<SidebarPeer>- The name says it all. It's the
<Sidebar>'s peer. The boring one. - Typically holds your app's main content, but honestly, you can put anything here.
- The name says it all. It's the
Before diving deeper, let's play with a simple demo and peek at the code:
Remember: the default shortcut for toggling the sidebar is option/alt + b.
DEEP DIVE: Noticed this is very different from Shadcn's Sidebar?
Yep, sharp eye!
Again, everything in our sidebar component stems from , which is really just common sense / practical observations.
Without a solid spec, component design goes wrong. It might look cool initially, but can lead to disaster later.
1️⃣ The Sidebar
Our <Sidebar> uses @uitimate/drawer (we call it the "mobile sidebar")
on small screens. This leads to these scenarios:
- You only want a desktop sidebar (i.e., it looks the same on all screen sizes).
- You just want to use our solution regardless.
- Other cases are probably rare or have straightforward solutions.
The first case is covered next. Here's what you need for the 2nd case:
Any prop or class you pass to <Sidebar> gets forwarded to both the desktop and mobile sidebars (FYI: the desktop sidebar is just a styled div).
Since mobile and desktop sidebar layouts often differ, our policy is: when using <Sidebar>, you MUST explicitly define the inner layout for each using
<Sidebar.Mobile> and <Sidebar.Desktop>:
As the code snippet shows, you MUST also include <DrawerHeader> inside <Sidebar.Mobile>.
Wondering why, or why <Sidebar.Mobile> & <Sidebar.Desktop> even exist? Check the source code!
2️⃣ The SidebarLayout
This component does most of the heavy lifting (more on that later) to make the sidebar work smoothly. Let's cover some key points, starting with case #1 from the previous section.
It's actually the easiest: just set enableMobileSidebar={false} on <SidebarLayout>
(then you don't need <Sidebar.Mobile> or <Sidebar.Desktop> anymore).
Now, placement: where should <Sidebar> go inside <SidebarLayout>? This only matters for desktop:
{/* To have the left Sidebar: */}
<SidebarLayout>
<Sidebar/>
<SidebarPeer/>
</SidebarLayout>
{/* To have the right Sidebar: */}
<SidebarLayout>
<SidebarPeer/>
<Sidebar/>
</SidebarLayout>
After placing it, you MUST declare the directions for both desktop and mobile sidebars using the mandatory directions prop on <SidebarLayout>.
Here's the TypeScript definition (check the for an example):
directions: [
desktopSidebarDirection: "left" | "right",
mobileSidebarDirection?: "left" | "right" | "top" | "bottom"
]
DEEP DIVE: The placement and directions seem kinda redundant?
Yeah, a bit.
But many sidebar libraries require a similar prop. Why? Auto-detecting direction makes the component code way too complex and unreliable.
Plus, explicitly setting the mobile sidebar direction makes sense, since it often differs from the desktop direction (pretty common, actually).
Since you have to specify the mobile direction anyway, why not just declare both together? It makes both directions super explicit and clear!
Seen this way, still think it's redundant?
For other props and concepts, check out these demos and their code snippets:
3️⃣ Tip
Helpful data-* attributes are added to all family components reflecting their states.
Inspect them in your browser's dev tools to learn more!
Let's go! For more on the components and cool demos, check the API reference page.