M
Marai.UI v1.0.0-alpha.7

Sidebar

A composable sidebar for app-shell and dashboard layouts. Supports structured header, content, and footer regions with a built-in collapsed state and full styling override support.

Overview

The MSidebar component provides a vertical navigation panel composed of four parts: MSidebar, MSidebarHeader, MSidebarContent, and MSidebarFooter. The header holds branding or an app title, the content area holds navigation links and scrolls independently, and the footer holds secondary info such as version or user details. A built-in Collapsed parameter switches the sidebar to an icon-only narrow width without any layout changes.

Usage

Add the namespace import to use the component.

razor 
@using Marai.UI.Components.MSidebar

Basic Usage

A sidebar with header, navigation links, and a footer placed alongside a main content area:

Preview
Main content area
razor 
<MSidebar>
    <MSidebarHeader>
        <svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="2"
             stroke-linecap="round" stroke-linejoin="round" viewBox="0 0 24 24" aria-hidden="true">
            <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
        </svg>
        Marai UI
    </MSidebarHeader>
    <MSidebarContent>
        <a href="/dashboard" class="flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium text-foreground hover:bg-primary/10 hover:text-primary">Dashboard</a>
        <a href="/components" class="flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium text-muted-foreground hover:bg-primary/10 hover:text-primary">Components</a>
        <a href="/settings" class="flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium text-muted-foreground hover:bg-primary/10 hover:text-primary">Settings</a>
    </MSidebarContent>
    <MSidebarFooter>
        <span class="text-xs text-muted-foreground">v1.0.0</span>
    </MSidebarFooter>
</MSidebar>
<div class="flex-1 p-4 text-sm text-muted-foreground">Main content area</div>

Examples

Collapsed State

Set Collapsed="true" to render the sidebar at icon-only width (w-16 instead of w-64). Navigation items inside MSidebarContent should be adjusted to show only icons in this state.

Preview
Main content area
razor 
<MSidebar Collapsed="true">
    <MSidebarHeader>
        <svg width="18" height="18" fill="none" stroke="currentColor" stroke-width="2"
             stroke-linecap="round" stroke-linejoin="round" viewBox="0 0 24 24" aria-hidden="true">
            <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
        </svg>
    </MSidebarHeader>
    <MSidebarContent>
        <a href="/dashboard" class="flex items-center justify-center rounded-md px-3 py-2 text-muted-foreground hover:bg-primary/10 hover:text-primary">
            <svg width="16" height="16" fill="none" stroke="currentColor" stroke-width="2"
                 stroke-linecap="round" viewBox="0 0 24 24" aria-hidden="true">
                <rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/>
                <rect x="3" y="14" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/>
            </svg>
        </a>
    </MSidebarContent>
</MSidebar>
<div class="flex-1 p-4 text-sm text-muted-foreground">Main content area</div>

Class Override

Use the Class parameter on MSidebar or any sub-component to append custom Tailwind classes. Useful for background overrides, border additions, or custom spacing.

Preview
Main content area
razor 
<MSidebar Class="bg-muted/40">
    <MSidebarHeader Class="border-b border-border">My App</MSidebarHeader>
    <MSidebarContent>
        <a href="/" class="flex items-center gap-2 rounded-md px-3 py-2 text-sm text-muted-foreground hover:bg-primary/10 hover:text-primary">Home</a>
    </MSidebarContent>
</MSidebar>
<div class="flex-1 p-4 text-sm text-muted-foreground">Main content area</div>

Customization

Custom Tailwind CSS Classes

Use the Class parameter on any sub-component to append Tailwind utility classes. The classes are combined with the component's base styles.

Customization Examples
  • Background: Class="bg-muted/40" on MSidebar for a subtle tinted background
  • Header border: Class="border-b border-border" on MSidebarHeader adds a separator
  • Footer border: Class="border-t border-border" on MSidebarFooter adds a separator
  • Spacing: Class="gap-2" on MSidebarContent increases link spacing
  • Width: Class="w-72" on MSidebar overrides the default 256px width

Standard HTML Attributes

All sub-components pass arbitrary HTML attributes through to their root element via AdditionalAttributes. You can add ARIA attributes, data attributes, and event handlers directly on any sub-component.

Accessibility

  • MSidebar renders as a semantic <aside> element for landmark navigation
  • MSidebarContent renders as <nav> — add aria-label="Sidebar navigation" when multiple nav landmarks exist on the page
  • In collapsed state, hide link text visually using sr-only rather than removing it, so screen readers still announce link destinations
  • Icon-only links in collapsed mode should include aria-label or a visually-hidden span
  • Sub-components can receive arbitrary ARIA attributes via AdditionalAttributes

API Reference

MSidebar

Parameter Type Default Description
ChildContent RenderFragment? null Slot for MSidebarHeader, MSidebarContent, and MSidebarFooter.
Collapsed bool false When true, renders the sidebar at icon-only width (w-16 instead of w-64).
Class string? null Additional CSS classes appended to the outer <aside> element.
AdditionalAttributes Dictionary<string, object>? null Arbitrary HTML attributes passed through to the <aside> element.

MSidebarHeader

Parameter Type Default Description
ChildContent RenderFragment? null Logo, app name, or any branding content.
Class string? null Additional CSS classes appended to the header container.
AdditionalAttributes Dictionary<string, object>? null Arbitrary HTML attributes passed through to the wrapper <div>.

MSidebarContent

Parameter Type Default Description
ChildContent RenderFragment? null Navigation links or any scrollable content. Expands to fill available vertical space.
Class string? null Additional CSS classes appended to the <nav> element.
AdditionalAttributes Dictionary<string, object>? null Arbitrary HTML attributes passed through to the <nav> element (e.g. aria-label).

MSidebarFooter

Parameter Type Default Description
ChildContent RenderFragment? null Version info, user avatar, or any bottom-pinned content.
Class string? null Additional CSS classes appended to the footer container.
AdditionalAttributes Dictionary<string, object>? null Arbitrary HTML attributes passed through to the wrapper <div>.

Styling Details

Base Classes

Each sub-component has a fixed base class that you extend via Class:

Sub-component State Base Classes
MSidebar Default flex h-full w-64 flex-col border-r border-border bg-background
MSidebar Collapsed flex h-full w-16 flex-col border-r border-border bg-background
MSidebarHeader — flex shrink-0 items-center gap-2 px-4 py-3 font-semibold text-foreground
MSidebarContent — flex flex-1 flex-col gap-1 overflow-y-auto px-2 py-2
MSidebarFooter — flex shrink-0 items-center gap-2 px-4 py-3
Best Practices
  • Place MSidebar in a flex or grid layout alongside a main content area, both sharing the full viewport height
  • Set height: 100vh or h-full on the parent container so the sidebar fills the screen
  • Use MSidebarContent's built-in overflow-y-auto to handle long navigation lists without page scroll
  • Keep MSidebarFooter content minimal — version info, a user avatar, or a single action