diff --git a/components/button/files/index.blade.php b/components/button/files/index.blade.php
index 440dda8..aca11a0 100644
--- a/components/button/files/index.blade.php
+++ b/components/button/files/index.blade.php
@@ -25,7 +25,7 @@
 $sizeClasses = match($size) { 
     'lg' => '[:where(&)]:h-12 text-md' . ' '. ( $squared ? 'w-12': ($icon ? 'ps-4' : 'ps-5') . ' ' . ($iconAfter ? 'pe-4' : 'pe-5')),
     'md' => '[:where(&)]:h-10 text-base' . ' '. ( $squared ? 'w-10': ($icon ? 'ps-3' : 'ps-4') . ' ' . ($iconAfter ? 'pe-3' : 'pe-4')), // default
-    'sm' => '[:where(&)]:h-8 text-sm' . ' '. ( $squared ? 'w-8': ($icon ? 'ps-2' : 'ps-3') . ' ' . ($iconAfter ? 'pe-2' : 'pe-3')),
+    'sm' => '[:where(&)]:h-9 text-sm' . ' '. ( $squared ? 'w-9': ($icon ? 'ps-2' : 'ps-3') . ' ' . ($iconAfter ? 'pe-2' : 'pe-3')),
     'xs' => '[:where(&)]:h-6 text-xs' . ' '. ( $squared ? 'w-6': ($icon ? 'ps-1' : 'ps-2') . ' ' . ($iconAfter ? 'pe-1' : 'pe-2')),
     default => '[:where(&)]:h-10 text-sm' . ' '. ( $squared ? 'w-10': ($icon ? 'ps-3' : 'ps-4') . ' ' . ($iconAfter ? 'pe-3' : 'pe-4')),
 };
@@ -82,7 +82,7 @@
 // Determine variant-specific classes for background, text, borders, and hover states
 $variantClasses = match($variant){
     'primary' => [
-        'bg-[var(--color-primary)] hover:bg-[--alpha(var(--color-primary)/50%)', // Background color 
+        'bg-[var(--color-primary)] hover:bg-[var(--color-primary)]/90', // Background color 
         'text-[var(--color-primary-fg)]', // Text color
         'border border-black/10 dark:border-0', // Border styles
         $colors => filled($color)
@@ -96,13 +96,13 @@
         ' bg-transparent'
     ],
     'outline' => [
-        'border border-[--alpha(var(--color-primary)/50%)] hover:border-[color-mix(in_oklab,_var(--color-primary),_black_20%)]', // Border
-        'bg-[--alpha(var(--color-primary)/5%)] hover:bg-[--alpha(var(--color-primary)/10%)]', // Background
+        'border border-[--alpha(var(--color-primary)/20%)] hover:border-[--alpha(var(--color-primary)/25%)]', // Border
+        'bg-[--alpha(var(--color-primary)/5%)] hover:bg-[--alpha(var(--color-primary)/7%)]', // Background
         'text-[var(--color-primary)]', 
         $colors => filled($color), // Ensure variables are set
     ],
     'ghost' => [
-        'bg-transparent hover:bg-neutral-800/5 dark:hover:bg-white/15', // Background colors
+        'bg-transparent hover:bg-[--alpha(var(--color-neutral-900)/5%)] dark:hover:bg-[--alpha(var(--color-white)/5%)]', // Background colors
         'text-neutral-800 dark:text-white' // Text colors
     ],
     'danger' =>[
@@ -116,11 +116,10 @@
 
 // Assemble base button classes, including layout, disabled states, and conditional styles
 $classes = [
-    'relative inline-flex items-center font-medium justify-center gap-x-2 whitespace-nowrap transition-colors duration-200',
-    '[contain:layout]', // fix for chrome bug with loading: nothing outside effect this internal layout,
+    'relative [:where(&)]:inline-flex items-center font-medium justify-center gap-x-2 whitespace-nowrap transition-colors duration-200',
     'disabled:opacity-55 dark:disabled:opacity-55 disabled:cursor-default disabled:pointer-events-none cursor-pointer',
     '[&_a]:no-underline [&_a]:decoration-none [&_a:hover]:no-underline' => $variant !== 'none' , // Handle anchor tags inside the button
-    'rounded-field' => $variant !== 'none' , // Apply rounding unless variant is 'none'
+    '[:where(&)]:rounded-field' => $variant !== 'none' , // Apply rounding unless variant is 'none'
     
     // Handling loading logic via CSS: Show loading indicator as flex and set opacity-0 on its siblings
     '[&>[data-loading=true]:first-child]:flex', // Override 'hidden' to display the loading div during loading
@@ -177,7 +176,7 @@
     @endif
 
     @if($slot->isNotEmpty())
-        <span >
+        <span data-text>
             {{ $slot }}
         </span>
     @endif
diff --git a/components/checkbox/files/index.blade.php b/components/checkbox/files/index.blade.php
index e61014a..db38c91 100644
--- a/components/checkbox/files/index.blade.php
+++ b/components/checkbox/files/index.blade.php
@@ -1,8 +1,3 @@
-{{-- 
-    Custom checkbox component that handles both individual and group states
-    Supports Livewire and Alpine.js model binding with automatic state synchronization
---}}
-
 @aware([
     'variant' => 'default'
 ])
diff --git a/components/dropdown/config.yml b/components/dropdown/config.yml
index ca5fc59..c666e16 100644
--- a/components/dropdown/config.yml
+++ b/components/dropdown/config.yml
@@ -3,6 +3,7 @@ files:
   item: resources/views/components/ui/dropdown/item.blade.php
   submenu: resources/views/components/ui/dropdown/submenu.blade.php
   group: resources/views/components/ui/dropdown/group.blade.php
+  checkbox-or-radio: resources/views/components/ui/dropdown/checkbox-or-radio.blade.php
   separator: resources/views/components/ui/dropdown/separator.blade.php
 dependencies:
   internal: [icon]
\ No newline at end of file
diff --git a/components/dropdown/files/checkbox-or-radio.blade.php b/components/dropdown/files/checkbox-or-radio.blade.php
new file mode 100644
index 0000000..75c2195
--- /dev/null
+++ b/components/dropdown/files/checkbox-or-radio.blade.php
@@ -0,0 +1,106 @@
+@aware([
+    'radio'=> false,
+    'checkbox' => false,
+    'disabled' => false,
+    'name' => null,
+    'checkboxVariant' => false,
+    'icon' => null,
+    'shortcut' => null
+])
+
+<!-- prevent those props from been part of the attributes bag... -->
+@props([
+    'classes' => '',
+    'value' => '',
+    'iconClasses' => ''
+])
+
+@php
+    $role = $checkbox ? 'menuitemcheckbox' : 'menuitemradio';
+   
+@endphp
+
+
+<label
+    {{ $attributes
+        ->whereDoesntStartWith(['wire:model', 'x-model'])
+        ->class(Arr::toCssClasses($classes))
+    }}
+    role="{{ $role }}"
+    aria-disabled="{{ $disabled ? 'true' : 'false' }}"
+    data-slot="dropdown-item"
+    x-data="{ checked: false }"
+    x-init="queueMicrotask(() => checked = $refs.input.checked)"
+    x-bind:aria-checked="checked"
+    x-on:keydown.enter.prevent.stop="$refs.input.click()"
+    x-on:keydown.space.prevent.stop="$refs.input.click()"
+>
+    <input
+        type="{{ $checkbox ? 'checkbox' : 'radio' }}"
+        {{ $attributes->whereStartsWith(['wire:model', 'x-model']) }}
+        value="{{ $value }}"
+        x-ref="input"
+        x-on:click="checked = !checked"
+        @if ($name) name="{{ $name }}" @endif
+        @disabled($disabled)
+        class="peer sr-only"
+    />
+
+    @if ($checkboxVariant)
+        <div class="relative inline-grid place-items-center size-5 mr-2">
+            {{-- Checkbox background --}}
+            <span
+                class="
+                    size-4.5 rounded ring-1 
+                    ring-neutral-100 dark:ring-white/10
+                    transition shadow
+                "
+                x-bind:class="{
+                    'ring-2 bg-[var(--color-primary)]': checked,
+                    'ring-1': !checked
+                }"
+            ></span>
+            <x-ui.icon 
+                name="check" 
+                class="
+                    absolute size-4 text-(--color-primary-fg)!
+                    transition-all duration-200
+                "
+                x-bind:class="{
+                    'opacity-100 scale-100': checked,
+                    'opacity-0 scale-75': !checked
+                }" 
+            />
+        </div>
+    @else
+        <x-ui.icon
+            name="check"
+            variant="mini"
+            class="{{ Arr::toCssClasses([
+                ...$iconClasses,
+                'opacity-0 peer-checked:opacity-100 transition-opacity duration-150',
+            ]) }}"
+            aria-hidden="true"
+        />
+    @endif
+    @if (filled($icon))
+        <x-ui.icon
+            :name="$icon"
+            :variant="$iconVariant"
+            :attributes="$iconAttributes"
+            data-slot="right-icon"
+        />
+    @endif
+
+    @if($slot->isNotEmpty())
+        <span class="col-start-3 whitespace-nowrap flex items-center justify-between gap-4">
+            <span>{{ $slot }}</span>
+
+            @if(filled($shortcut))
+                <x-ui.kbd>
+                    {{ $shortcut }}
+                </x-ui.kbd>
+            @endif
+        </span>
+    @endif
+</label>
\ No newline at end of file
diff --git a/components/dropdown/files/group.blade.php b/components/dropdown/files/group.blade.php
index be06765..0db0b95 100644
--- a/components/dropdown/files/group.blade.php
+++ b/components/dropdown/files/group.blade.php
@@ -1,7 +1,6 @@
-{{-- dropdown/group.blade.php --}}
 @props(['label' => null])
 
-<div {{ $attributes->merge(['class' => 'pt-1 contents']) }}>
+<div {{ $attributes->merge(['class' => 'pt-1 space-y-(--dropdown-padding) contents']) }}>
     @if($label)
         <div class="text-xs text-start col-span-full px-[calc(--spacing(1.5)_+_var(--dropdown-padding))] font-medium text-neutral-500 dark:text-neutral-400 tracking-wide">
             {{ $label }}
diff --git a/components/dropdown/files/index.blade.php b/components/dropdown/files/index.blade.php
index c3db381..518d9da 100644
--- a/components/dropdown/files/index.blade.php
+++ b/components/dropdown/files/index.blade.php
@@ -1,16 +1,24 @@
 @props([
     'position' => 'bottom-center',
     'teleport' => 'body',
-    'portal' => false 
+    'portal' => false,
+    'trap' => false,
+    'offset' => 6,
+    'checkbox' => false,
+    'radio' => false,
+    'resetFocus' => false
 ])
 
 @php
+    $isDefaultDropdownVariant = $checkbox || $radio;
     $classes = [
         'isolate z-50',
-        'grid grid-cols-[auto_1fr_auto]',
+        'grid grid-cols-[auto_1fr_auto]' => !$isDefaultDropdownVariant ,
+        'grid grid-cols-[auto_auto_1fr_auto]' => $isDefaultDropdownVariant,
         '[:where(&)]:max-w-96 [:where(&)]:min-w-40 text-start',
-        'bg-white dark:bg-neutral-900 border border-black/10 dark:border-white/10 space-y-0.5',
-        'rounded-(--dropdown-radius) p-(--dropdown-padding) [--dropdown-radius:var(--radius-box)] [--dropdown-padding:--spacing(.75)]',
+        'bg-white dark:bg-neutral-900 border border-black/10 dark:border-white/10',
+        '[--dropdown-radius:var(--radius-box)] [--dropdown-padding:--spacing(.75)]
+         rounded-(--dropdown-radius) p-(--dropdown-padding) space-y-1',
     ];  
 @endphp
 
@@ -18,12 +26,13 @@
     <div
         x-data="{
             open: false,
+            resetFocus:@js($resetFocus),
             toggle() {
                 if (this.open) {
                     return this.close()
                 }
 
-                this.$refs.button.focus()
+                $focus.getFirst().focus()
                 this.open = true
             },
             isOpen(){
@@ -32,10 +41,11 @@
             close(focusAfter) {
                 if (! this.open) return
 
-                this.open = false
+                this.open = false;
 
-                focusAfter && focusAfter.focus()
+                focusAfter && this.resetFocus && requestAnimationFrame(() => $focus.getFirst().focus());
             },
+
             handleFocusInOut(event) {
                 const panel = this.$refs.panel
                 const button = this.$refs.button
@@ -55,6 +65,7 @@
             },
 
         }"
+        wire:ignore
         x-on:keydown.escape.prevent.stop="close($refs.button)"
         x-on:focusin.window="handleFocusInOut($event)"
         x-id="['dropdown-button']"
@@ -64,13 +75,14 @@ class="relative"
         <!-- Button -->
         <div 
             x-ref="button"
-            {{ $button->attributes->class('flex items-center px-2 py-1 rounded-field') }}
+            {{ $button->attributes }}
             x-on:keydown.tab.prevent.stop="$focus.focus($focus.within($refs.panel).getFirst())"
             x-on:keydown.down.prevent.stop="$focus.focus($focus.within($refs.panel).getFirst())"
             x-on:keydown.space.stop.prevent="toggle()"
             x-on:keydown.enter.stop.prevent="toggle()"
             x-on:click="toggle()"
             x-bind:aria-expanded="open"
+            x-bind:data-open="open"
             x-bind:aria-controls="$id('dropdown-button')"
         >
             {{ $button }}
@@ -82,8 +94,13 @@ class="relative"
         
         <div 
             x-show="open"
+
+            @if ($trap)
+                x-trap="open"            
+            @endif
+            
             x-ref="panel"
-            x-anchor.{{ $position }}.offset.6="$refs.button"
+            x-anchor.{{ $position }}.offset.{{ $offset }}="$refs.button;"
             x-on:keydown.down.prevent.stop="$focus.next()"
             x-on:keydown.up.prevent.stop="$focus.prev()"
             x-on:keydown.home.prevent.stop="$focus.first()"
@@ -98,7 +115,12 @@ class="relative"
             x-transition:leave-end="opacity-0 scale-95"
             x-on:click.away="close($refs.button)"
             x-bind:id="$id('dropdown-button')"
-            style="display: none; backdrop-filter: blur(64px); -webkit-backdrop-filter: blur(64px);"
+            style="display: none;"
+            @if($radio)
+                role="radiogroup"
+            @else
+                role="menu"
+            @endif
             {{ $menu->attributes->class(Arr::toCssClasses($classes)) }}
         >
             {{ $menu }}
diff --git a/components/dropdown/files/item.blade.php b/components/dropdown/files/item.blade.php
index ed86cb6..fecf82e 100644
--- a/components/dropdown/files/item.blade.php
+++ b/components/dropdown/files/item.blade.php
@@ -1,3 +1,4 @@
+@aware(['checkbox' => false, 'radio' => false, 'checkboxVariant' => false])
 
 @props([
     'disabled' => false,
@@ -5,46 +6,99 @@
     'iconVariant' => 'mini',
     'shortcut' => null,
     'variant' => 'soft',
-    'as'=>'div'
+    'as' => 'button',
+    'active' => false,
+    'value' => null,
+    'name' => null,
+    'checkboxVariant' => false,
+    'readOnly' => false
 ])
 
 @php
+    $isDefaultDropdownVariant = !($checkbox || $radio);
 
-$variantClasses = match($variant) {
-    'soft' => 'hover:bg-neutral-100 focus:bg-neutral-100 dark:hover:bg-white/5 dark:focus:bg-white/5',
-    'danger' => 'hover:text-red-600 hover:bg-red-50 dark:hover:bg-red-400/20 dark:hover:text-red-400 focus:text-red-600 focus:bg-red-50 dark:focus:bg-red-400/20 dark:focus:text-red-400'
-};
+    $variantClasses = match ($variant) {
+        'soft' => 'hover:bg-neutral-100 focus-within:bg-neutral-100 dark:hover:bg-white/5 dark:focus-within:bg-white/5',
+        'danger' => 'hover:text-red-600 hover:bg-red-50 dark:hover:bg-red-400/20 dark:hover:text-red-400 focus-within:text-red-600 focus-within:bg-red-50 dark:focus-within:bg-red-400/20 dark:focus-within:text-red-400',
+        default => '',
+    };
 
-$iconClasses = [
-    'inline-flex shrink-0 mr-2',
-    match($variant){
-        'soft' => '',
-        'danger' => 'hover:text-red-500! dark:hover:text-red-400! focus:text-red-500! dark:focus:text-red-400!'
-    }
-];
+    $iconClasses = [
+        'inline-flex shrink-0 mr-2',
+        match ($variant) {
+            'soft' => '',
+            'danger' => 'group-hover:text-red-500! dark:group-hover:text-red-400! group-focus-within:text-red-500! dark:group-focus-within:text-red-400!',
+            default => '',
+        },
+    ];
+
+    $iconAttributes = (new Illuminate\View\ComponentAttributeBag())
+        ->class($iconClasses)
+        ->merge(['aria-hidden' => 'true']);
 
-$iconAttributes = (new Illuminate\View\ComponentAttributeBag())->class($iconClasses);
+    $value ??= trim($slot->__toString());
 
-$classes = [
-    'grid grid-cols-subgrid col-span-2', // used to add a right gap to all item if there is at least an item has an icon
-    'w-full px-3 py-1.5 text-sm transition-colors duration-200 text-start',
-    'text-neutral-800 dark:text-white text-neutral-800 dark:text-white', // text colors
-    'rounded-[calc(var(--dropdown-radius)-var(--dropdown-padding))] ', // adjust the rounding based on outer dropdown rounding
-    'focus:outline-none',
-    'opacity-50 cursor-not-allowed text-neutral-500 dark:text-neutral-400' => $disabled,
-    $variantClasses .' '.' cursor-pointer' => !$disabled
-];
+    $classes = [
+        'grid grid-cols-subgrid group relative overflow-hidden',
+        'col-span-2' => $isDefaultDropdownVariant,
+        'col-span-3' => ! $isDefaultDropdownVariant,
+        'w-full px-2 py-1.5 text-sm transition-colors duration-200 text-start',
+        'text-neutral-800 dark:text-white',
+        'rounded-[calc(var(--dropdown-radius)-var(--dropdown-padding))]',
+        'focus-within:outline-none',
+        'data-active:bg-neutral-950/[3%] dark:data-active:bg-white/[3%]',
+        $variantClasses . ' cursor-pointer' => ! $disabled,
+        'opacity-50 cursor-not-allowed text-neutral-500 dark:text-neutral-400' => $disabled,
+    ];
 
+    if ($active) {
+        $attributes['data-active'] = 'true';
+    }
 @endphp
 
-<x-ui.button.abstract :$as :attributes="$attributes->class(Arr::toCssClasses($classes))->merge(['disabled' => $disabled, 'tabindex' => $disabled ? '-1' : '0'])" data-slot="dropdown-item">
-    @if(filled($icon))
-        <x-ui.icon :name="$icon" :variant="$iconVariant" :attributes="$iconAttributes"  data-slot="right-icon"/>
-    @endif
-
-    @if($slot->isNotEmpty())
-        <span class="col-start-2">
-            {{ $slot }}
-        </span>
-    @endif
-</x-ui.button.abstract>
+@if ($isDefaultDropdownVariant)
+    <x-ui.button.abstract
+        :$as
+        :attributes="$attributes
+            ->class(Arr::toCssClasses($classes))
+            ->merge([
+                'disabled' => $disabled,
+                'tabindex' => $disabled ? '-1' : '0',
+                'aria-disabled' => $disabled ? 'true' : 'false',
+                'role' => 'menuitem',
+            ])"
+        data-slot="dropdown-item"
+    >
+        @if (filled($icon))
+            <x-ui.icon
+                :name="$icon"
+                :variant="$iconVariant"
+                :attributes="$iconAttributes"
+                data-slot="right-icon"
+            />
+        @endif
+
+       <span class="col-start-2 whitespace-nowrap flex items-center justify-between gap-4_">
+                <span class="flex-1">{{ $slot }}</span>
+                
+                @if(filled($shortcut))
+                    <x-ui.kbd>
+                        {{ $shortcut }}
+                    </x-ui.kbd>
+                @endif
+            </span>
+    </x-ui.button.abstract>
+@elseif($readOnly)
+    <div class="text-center col-span-full text-neutral-800 dark:text-white w-full px-3 py-1.5 text-sm" {{ $attributes }}>
+        {{ $slot }}
+    </div>
+@else   
+   <x-ui.dropdown.checkbox-or-radio 
+        :$attributes
+        :$classes
+        :$iconClasses
+        :$value
+    >
+        {{ $slot }}
+    </x-ui.dropdown.checkbox-or-radio>
+@endif
\ No newline at end of file
diff --git a/components/dropdown/files/separator.blade.php b/components/dropdown/files/separator.blade.php
index 0ef01de..2d4b067 100644
--- a/components/dropdown/files/separator.blade.php
+++ b/components/dropdown/files/separator.blade.php
@@ -1 +1,6 @@
-<div {{ $attributes->merge(['class' => 'my-1 -mx-(--dropdown-padding) h-px grid-cols-subgrid col-span-full bg-gray-800/5 dark:bg-white/10']) }}></div>
+<div 
+    {{ 
+        $attributes->merge(['class' => '-mx-(--dropdown-padding) h-[0.75px] grid-cols-subgrid col-span-full    bg-neutral-800/5 dark:bg-white/10']) 
+    }}
+    data-slot="dropdown-separator"
+></div>
diff --git a/components/dropdown/files/submenu.blade.php b/components/dropdown/files/submenu.blade.php
index 778d1f5..1dcb5b3 100644
--- a/components/dropdown/files/submenu.blade.php
+++ b/components/dropdown/files/submenu.blade.php
@@ -3,13 +3,21 @@
     'disabled' => false,
 ])
 
+@php
+    $classes=[
+        'contents',
+        // if this followed by a separator or another submenu, compensite the missed space-y-(--dropdown-padding) caused by `contents` class
+        '[&+[data-slot=dropdown-separator]]:mt-1',
+        '[&+[data-slot=dropdown-submenu]_[data-slot=dropdown-item]]:mt-1',
+    ]
+@endphp
 
-<div x-data="{ isOpen: false }" class="contents">
+<div x-data="{ isOpen: false }" 
+    class="{{ Arr::toCssClasses($classes) }}"
+    data-slot="dropdown-submenu"
+>
     <x-ui.dropdown.item 
-        {{ $attributes->merge([
-            'disabled' => $disabled,
-            'tabindex' => $disabled ? '-1' : '0'
-        ]) }}
+        {{ $attributes->merge([ 'disabled' => $disabled, 'tabindex' => $disabled ? '-1' : '0' ]) }}
         x-ref="trigger"
         x-on:mouseenter="isOpen = true"
         x-on:mouseleave="isOpen = false"
@@ -21,8 +29,12 @@
                 if (el) $focus.focus($focus.within(el).getFirst());
             })
         "
+        active
     >
-        {{ $label }}
+        <div class="flex items-center justify-between">
+            {{ $label }}
+            <x-ui.icon name="chevron-right" variant="mini" class="inline-flex shrink-0 ml-2"/>
+        </div>
     </x-ui.dropdown.item>
 
     <div 
@@ -46,7 +58,7 @@
         style="display: none;"
         {{ $attributes->class([
             'bg-white dark:bg-neutral-900 ',
-            'z-10 max-w-96 min-w-40 text-start shadow-md  border border-black/10 dark:border-white/10',
+            'z-10 [:where(&)]:max-w-96 [:where(&)]:min-w-40 text-start shadow-md border border-black/10 dark:border-white/10',
             'grid grid-cols-[auto_1fr_auto]',
             'rounded-(--dropdown-radius) p-(--dropdown-padding) [--dropdown-radius:var(--radius-box)] [--dropdown-padding:--spacing(.75)]',
         ]) }}
diff --git a/components/dropdown/usage.md b/components/dropdown/usage.md
index 8b6898b..ccd6bc1 100644
--- a/components/dropdown/usage.md
+++ b/components/dropdown/usage.md
@@ -129,7 +129,7 @@ Add visual clarity with icons for better user experience.
     </x-slot:menu>
 </x-ui.dropdown>
 ```
-<!-- 
+
 ### Items with Shortcuts
 
 Display keyboard shortcuts for power users.
@@ -186,7 +186,7 @@ Display keyboard shortcuts for power users.
         </x-ui.dropdown.item>
     </x-slot:menu>
 </x-ui.dropdown>
-``` -->
+```
 
 ### Linked Items
 
@@ -768,6 +768,284 @@ Combine all features for sophisticated dropdown menus.
 
 Here's the section to add to your dropdown documentation:
 
+## Checkbox Variant
+
+The dropdown now supports checkbox items for multi-selection scenarios. When enabled, items can be toggled on/off independently.
+
+### Basic Checkbox Usage
+
+@blade
+<x-demo class="flex justify-center">
+    <x-ui.dropdown checkbox>
+        <x-slot:button>
+            <x-ui.button icon="funnel" variant="soft" size="sm">
+                Filters
+            </x-ui.button>
+        </x-slot:button>
+        
+        <x-slot:menu>
+            <x-ui.dropdown.item wire:model="filters.active">
+                Active Items
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="filters.archived">
+                Archived Items
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="filters.deleted">
+                Deleted Items
+            </x-ui.dropdown.item>
+        </x-slot:menu>
+    </x-ui.dropdown>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.dropdown checkbox>
+    <x-slot:button>
+        <x-ui.button icon="funnel" variant="soft" size="sm">
+            Filters
+        </x-ui.button>
+    </x-slot:button>
+    
+    <x-slot:menu>
+        <x-ui.dropdown.item wire:model="filters.active">
+            Active Items
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="filters.archived">
+            Archived Items
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="filters.deleted">
+            Deleted Items
+        </x-ui.dropdown.item>
+    </x-slot:menu>
+</x-ui.dropdown>
+```
+
+### Custom Checkbox Variant
+
+Use `checkboxVariant` for a more prominent checkbox style with visible checkboxes:
+
+@blade
+<x-demo class="flex justify-center">
+    <x-ui.dropdown checkbox checkboxVariant>
+        <x-slot:button>
+            <x-ui.button icon="funnel" variant="soft" size="sm">
+                Column Visibility
+            </x-ui.button>
+        </x-slot:button>
+        
+        <x-slot:menu>
+            <x-ui.dropdown.item readOnly>
+                Hidden Columns
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.separator/>
+            
+            <x-ui.dropdown.item wire:model="hiddenCols" value="probability">
+                Probability
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="hiddenCols" value="difficulty">
+                Difficulty
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="hiddenCols" value="status">
+                Status
+            </x-ui.dropdown.item>
+        </x-slot:menu>
+    </x-ui.dropdown>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.dropdown checkbox checkboxVariant>
+    <x-slot:button>
+        <x-ui.button icon="funnel" variant="soft" size="sm">
+            Column Visibility
+        </x-ui.button>
+    </x-slot:button>
+    
+    <x-slot:menu>
+        <x-ui.dropdown.item readOnly>
+            Hidden Columns
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.separator/>
+        
+        <x-ui.dropdown.item wire:model="hiddenCols" value="probability">
+            Probability
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="hiddenCols" value="difficulty">
+            Difficulty
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="hiddenCols" value="status">
+            Status
+        </x-ui.dropdown.item>
+    </x-slot:menu>
+</x-ui.dropdown>
+```
+
+**Differences:**
+- `checkbox`: Uses a minimal checkmark icon that appears when selected
+- `checkboxVariant`: Shows an actual checkbox UI element with background and border
+
+## Radio Variant
+
+For single-selection scenarios, use the radio variant:
+
+@blade
+<x-demo class="flex justify-center">
+    <x-ui.dropdown radio name="sortBy">
+        <x-slot:button>
+            <x-ui.button icon="arrows-up-down" variant="soft" size="sm">
+                Sort By
+            </x-ui.button>
+        </x-slot:button>
+        
+        <x-slot:menu>
+            <x-ui.dropdown.item wire:model="sortBy" value="name">
+                Name
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="sortBy" value="date">
+                Date
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="sortBy" value="size">
+                Size
+            </x-ui.dropdown.item>
+        </x-slot:menu>
+    </x-ui.dropdown>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.dropdown radio name="sortBy">
+    <x-slot:button>
+        <x-ui.button icon="arrows-up-down" variant="soft" size="sm">
+            Sort By
+        </x-ui.button>
+    </x-slot:button>
+    
+    <x-slot:menu>
+        <x-ui.dropdown.item wire:model="sortBy" value="name">
+            Name
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="sortBy" value="date">
+            Date
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="sortBy" value="size">
+            Size
+        </x-ui.dropdown.item>
+    </x-slot:menu>
+</x-ui.dropdown>
+```
+
+**Note:** Radio items require a `name` attribute to group them together.
+
+## Read-Only Items (Titles)
+
+Use `readOnly` items as non-interactive section titles or headers within your dropdown:
+
+@blade
+<x-demo class="flex justify-center">
+    <x-ui.dropdown checkbox checkboxVariant>
+        <x-slot:button>
+            <x-ui.button icon="adjustments-horizontal">
+                Display Options
+            </x-ui.button>
+        </x-slot:button>
+        
+        <x-slot:menu>
+            <x-ui.dropdown.item readOnly>
+                View Settings
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.separator/>
+            
+            <x-ui.dropdown.item wire:model="display.grid">
+                Grid View
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="display.list">
+                List View
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.separator/>
+            
+            <x-ui.dropdown.item readOnly>
+                Active Filters
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.separator/>
+            
+            <x-ui.dropdown.item wire:model="filters.active">
+                Show Active Only
+            </x-ui.dropdown.item>
+            
+            <x-ui.dropdown.item wire:model="filters.archived">
+                Show Archived
+            </x-ui.dropdown.item>
+        </x-slot:menu>
+    </x-ui.dropdown>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.dropdown checkbox checkboxVariant>
+    <x-slot:button>
+        <x-ui.button icon="adjustments-horizontal">
+            Display Options
+        </x-ui.button>
+    </x-slot:button>
+    
+    <x-slot:menu>
+        <x-ui.dropdown.item readOnly>
+            View Settings
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.separator/>
+        
+        <x-ui.dropdown.item wire:model="display.grid">
+            Grid View
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="display.list">
+            List View
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.separator/>
+        
+        <x-ui.dropdown.item readOnly>
+            Active Filters
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.separator/>
+        
+        <x-ui.dropdown.item wire:model="filters.active">
+            Show Active Only
+        </x-ui.dropdown.item>
+        
+        <x-ui.dropdown.item wire:model="filters.archived">
+            Show Archived
+        </x-ui.dropdown.item>
+    </x-slot:menu>
+</x-ui.dropdown>
+```
+
+**Benefits:**
+- Provides visual organization
+- Non-interactive, preventing accidental clicks
+- Spans full width for clear section separation
+- Styled differently from regular items
+
 ## Portal Mode
 
 The `portal` prop controls where the dropdown menu is rendered in the DOM. By default (`portal="false"`), the menu renders as a child of the dropdown component. When enabled (`portal="true"`), the menu is teleported to the end of the `<body>` element.
@@ -823,6 +1101,7 @@ When `portal="true"`, the dropdown menu loses access to parent CSS custom proper
 
 **Note:** The menu remains properly positioned via `x-anchor` regardless of portal usage.
 
+
 ## Component Props
 
 ### Dropdown (Main Component)
@@ -832,6 +1111,10 @@ When `portal="true"`, the dropdown menu loses access to parent CSS custom proper
 | `position` | string | `'bottom-center'` | No | Dropdown positioning: `bottom-center`, `bottom-start`, `bottom-end`, `top-center`, `top-start`, `top-end` |
 | `portal` | string | `null` | No | teleported dropdown: `portal` prop |
 | `class` | string | `''` | No | Additional CSS classes |
+| `checkbox` | boolean | `false` | No | Enable checkbox mode for multi-selection |
+| `radio` | boolean | `false` | No | Enable radio mode for single selection |
+| `resetFocus` | boolean | `false` | No | Return focus to trigger button when dropdown closes |
+| `checkboxVariant` | boolean | `false` | No | Use prominent checkbox UI (requires `checkbox="true"`) |
 
 ### Dropdown Item
 
@@ -845,6 +1128,9 @@ When `portal="true"`, the dropdown menu loses access to parent CSS custom proper
 | `variant` | string | `'soft'` | No | Visual variant: `soft`, `danger` |
 | `href` | string | `null` | No | URL for navigation items |
 | `class` | string | `''` | No | Additional CSS classes |
+| `readOnly` | boolean | `false` | No | Makes item non-interactive (useful as section title) |
+| `value` | string | `null` | No | Value for checkbox/radio items |
+| `name` | string | `null` | No | Name attribute for radio groups |
 
 ### Dropdown Group
 
diff --git a/components/empty/config.yml b/components/empty/config.yml
new file mode 100644
index 0000000..1879378
--- /dev/null
+++ b/components/empty/config.yml
@@ -0,0 +1,4 @@
+files:
+  contents: resources/views/components/ui/empty/contents.blade.php
+  index: resources/views/components/ui/empty/index.blade.php
+  media: resources/views/components/ui/empty/media.blade.php
\ No newline at end of file
diff --git a/components/empty/files/contents.blade.php b/components/empty/files/contents.blade.php
new file mode 100644
index 0000000..ad08f05
--- /dev/null
+++ b/components/empty/files/contents.blade.php
@@ -0,0 +1,3 @@
+<div {{ $attributes->merge(['class' => 'flex flex-col gap-3 items-center justify-center']) }}>
+    {{ $slot }}
+</div>
diff --git a/components/empty/files/index.blade.php b/components/empty/files/index.blade.php
new file mode 100644
index 0000000..32517bf
--- /dev/null
+++ b/components/empty/files/index.blade.php
@@ -0,0 +1,7 @@
+@props([
+    'variant' => 'default', 
+])
+
+<div {{ $attributes->class('flex flex-col items-center justify-center py-6 px-6 text-center') }}>
+    {{ $slot }}
+</div>
diff --git a/components/empty/files/media.blade.php b/components/empty/files/media.blade.php
new file mode 100644
index 0000000..c14a31a
--- /dev/null
+++ b/components/empty/files/media.blade.php
@@ -0,0 +1,7 @@
+@props([
+    'variant' => 'default', // default, icon
+])
+
+<div {{ $attributes->class('mb-4') }}>
+    {{ $slot }}
+</div>
diff --git a/components/empty/usage.md b/components/empty/usage.md
new file mode 100644
index 0000000..47ccbeb
--- /dev/null
+++ b/components/empty/usage.md
@@ -0,0 +1,451 @@
+---
+name: empty
+---
+
+## Introduction
+
+The `Empty` component provides **beautiful empty state placeholders** for when there's no data to display. It offers a flexible composition API for creating meaningful empty states that guide users toward the next action.
+
+## Installation
+
+Use the [sheaf artisan command](/docs/guides/cli-installation#content-component-management) to install the `empty` component easily:
+
+```bash
+php artisan sheaf:install empty
+```
+
+> Once installed, you can use the `<x-ui.empty />`, `<x-ui.empty.media />`, and `<x-ui.empty.contents />` components in any Blade view.
+
+## Usage
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-lg">
+        <x-ui.empty>
+            <x-ui.empty.media>
+                <x-ui.icon name="inbox" class="size-10" />
+            </x-ui.empty.media>
+
+            <x-ui.empty.contents>
+                <x-ui.heading>No results found</x-ui.heading>
+                <x-ui.text class="opacity-70">
+                    Try adjusting your filters or create a new item.
+                </x-ui.text>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+### Basic Empty State
+
+The most basic usage combines media (icon/image) with descriptive content:
+
+```blade
+<x-ui.empty>
+    <x-ui.empty.media>
+        <x-ui.icon name="inbox" class="size-10" />
+    </x-ui.empty.media>
+
+    <x-ui.empty.contents>
+        <x-ui.heading>No messages</x-ui.heading>
+        <x-ui.text class="opacity-70">
+            Your inbox is empty. Start a conversation!
+        </x-ui.text>
+    </x-ui.empty.contents>
+</x-ui.empty>
+```
+
+## Styling Variants
+
+Customize the appearance using Tailwind classes:
+
+### Bordered
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-2xl">
+        <x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+            <x-ui.empty.media>
+                <x-ui.icon name="folder-open" class="size-10" />
+            </x-ui.empty.media>
+            <x-ui.empty.contents>
+                <x-ui.heading>No items</x-ui.heading>
+                <x-ui.text class="opacity-70">Get started by creating your first item.</x-ui.text>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+    <!-- content -->
+</x-ui.empty>
+```
+
+### Background
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full ">
+        <x-ui.empty class="bg-neutral-50 dark:bg-white/5 rounded-box">
+            <x-ui.empty.media>
+                <x-ui.icon name="folder-open" class="size-10" />
+            </x-ui.empty.media>
+            <x-ui.empty.contents>
+                <x-ui.heading>No items</x-ui.heading>
+                <x-ui.text class="opacity-70">Get started by creating your first item.</x-ui.text>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.empty class="bg-neutral-50 dark:bg-white/5 rounded-box">
+    <!-- content -->
+</x-ui.empty>
+```
+
+## Media Styling
+
+Customize the media area with Tailwind classes:
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-2xl grid grid-cols-2 gap-6">
+        <x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+            <x-ui.empty.media>
+                <x-ui.icon name="inbox" class="size-10" />
+            </x-ui.empty.media>
+            <x-ui.empty.contents>
+                <x-ui.heading>Simple Icon</x-ui.heading>
+                <x-ui.text class="opacity-70">Default icon display</x-ui.text>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+        <!--  -->
+        <x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+            <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+                <x-ui.icon name="document" class="size-6" />
+            </x-ui.empty.media>
+            <x-ui.empty.contents>
+                <x-ui.heading>Icon with Circle</x-ui.heading>
+                <x-ui.text class="opacity-70">Circular background</x-ui.text>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<!-- Simple icon -->
+<x-ui.empty.media>
+    <x-ui.icon name="inbox" class="size-10" />
+</x-ui.empty.media>
+
+<!-- Icon with circular background -->
+<x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+    <x-ui.icon name="document" class="size-6" />
+</x-ui.empty.media>
+```
+
+## Examples
+
+### With Action Button
+
+Guide users to take action with a prominent button:
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-lg">
+        <x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+            <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+                <x-ui.icon name="document" class="size-6" />
+            </x-ui.empty.media>
+
+            <x-ui.empty.contents>
+                <x-ui.heading>No documents</x-ui.heading>
+                <x-ui.text class="opacity-70">
+                    You haven't created any documents yet.
+                </x-ui.text>
+
+                <x-ui.button size="sm" class="mt-3">
+                    Create document
+                </x-ui.button>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+    <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+        <x-ui.icon name="document" class="size-6" />
+    </x-ui.empty.media>
+
+    <x-ui.empty.contents>
+        <x-ui.heading>No documents</x-ui.heading>
+        <x-ui.text class="opacity-70">
+            You haven't created any documents yet.
+        </x-ui.text>
+
+        <x-ui.button size="sm" class="mt-3">
+            Create document
+        </x-ui.button>
+    </x-ui.empty.contents>
+</x-ui.empty>
+```
+
+### With Avatar Group
+
+Show team or user context in your empty state:
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-lg">
+        <x-ui.empty>
+            <x-ui.empty.media>
+                <x-ui.avatar.group>
+                    <x-ui.avatar circle src="/mohamed.png" name="Mohamed Charrafi" />
+                    <x-ui.avatar circle src="/youssef.jpeg" name="Youssef" />
+                    <x-ui.avatar circle>+1</x-ui.avatar>
+                </x-ui.avatar.group>
+            </x-ui.empty.media>
+            <!--  -->
+            <x-ui.empty.contents>
+                <x-ui.heading class="text-lg font-semibold">The Team Above</x-ui.heading>
+                <x-ui.text class="opacity-70">
+                    Start by contacting the team.
+                </x-ui.text>
+                <div class="flex gap-2 mt-4">
+                    <x-ui.button>Create</x-ui.button>
+                    <x-ui.button variant="ghost">Learn more</x-ui.button>
+                </div>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.empty>
+    <x-ui.empty.media>
+        <x-ui.avatar.group>
+            <x-ui.avatar circle src="/user1.png" name="User 1" />
+            <x-ui.avatar circle src="/user2.png" name="User 2" />
+            <x-ui.avatar circle>+3</x-ui.avatar>
+        </x-ui.avatar.group>
+    </x-ui.empty.media>
+
+    <x-ui.empty.contents>
+        <x-ui.heading class="text-lg font-semibold">The Team Above</x-ui.heading>
+        <x-ui.text class="opacity-70">
+            Start by contacting the team.
+        </x-ui.text>
+
+        <div class="flex gap-2 mt-4">
+            <x-ui.button>Create</x-ui.button>
+            <x-ui.button variant="ghost">Learn more</x-ui.button>
+        </div>
+    </x-ui.empty.contents>
+</x-ui.empty>
+```
+
+### Search Results Empty State
+
+Handle empty search results with helpful messaging:
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-lg">
+        <x-ui.empty>
+            <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+                <x-ui.icon name="magnifying-glass" class="size-6" />
+            </x-ui.empty.media>
+            <!--  -->
+            <x-ui.empty.contents class="">
+                <x-ui.heading>No results found</x-ui.heading>
+                <x-ui.text class="opacity-70 text-center">
+                    We couldn't find anything matching "your search". Try different keywords.
+                </x-ui.text>
+
+                <x-ui.button variant="outline" size="sm" class="mt-3">
+                    Clear search
+                </x-ui.button>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.empty>
+    <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+        <x-ui.icon name="magnifying-glass" class="size-6" />
+    </x-ui.empty.media>
+
+    <x-ui.empty.contents>
+        <x-ui.heading>No results found</x-ui.heading>
+        <x-ui.text class="opacity-70 text-center">
+            We couldn't find anything matching "{{ $searchQuery }}". Try different keywords.
+        </x-ui.text>
+
+        <x-ui.button variant="outline" size="sm" class="mt-3">
+            Clear search
+        </x-ui.button>
+    </x-ui.empty.contents>
+</x-ui.empty>
+```
+
+### In Table Context
+
+Use empty states within tables for better UX:
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-3xl rounded-box overflow-hidden">
+        <x-ui.table>
+            <x-ui.table.header>
+                <x-ui.table.columns>
+                    <x-ui.table.head>
+                        name
+                    </x-ui.table.head>
+                    <x-ui.table.head>
+                        type
+                    </x-ui.table.head>
+                    <x-ui.table.head>
+                        created at
+                    </x-ui.table.head>
+                    <x-ui.table.head>
+                        description
+                    </x-ui.table.head>
+                </x-ui.table.columns>
+            </x-ui.table.header>
+            <x-ui.table.rows>
+                    <x-ui.table.empty>
+                            <x-ui.empty>
+                                <x-ui.empty.media 
+                                    class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800"
+                                >
+                                    <x-ui.icon name="inbox" class="size-6" />
+                                </x-ui.empty.media>
+                                <x-ui.empty.contents>
+                                    <x-ui.heading>No data available</x-ui.heading>
+                                    <x-ui.text class="opacity-70">
+                                        Start by adding your first entry.
+                                    </x-ui.text>
+                                </x-ui.empty.contents>
+                            </x-ui.empty>
+                    </x-ui.table.empty>
+            </x-ui.table.rows>
+        </x-ui.table>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table>
+    <!-- header-->
+    <x-ui.table.rows>
+        @forelse ($items as $item)
+            <x-ui.table.row>
+                <!-- table cells -->
+            </x-ui.table.row>
+        @empty
+            <x-ui.table.row>
+                <x-ui.table.cell colspan="4" class="!p-0">
+                    <x-ui.empty>
+                        <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+                            <x-ui.icon name="inbox" class="size-6" />
+                        </x-ui.empty.media>
+                        <x-ui.empty.contents>
+                            <x-ui.heading>No data available</x-ui.heading>
+                            <x-ui.text class="opacity-70">
+                                Start by adding your first entry.
+                            </x-ui.text>
+                        </x-ui.empty.contents>
+                    </x-ui.empty>
+                </x-ui.table.cell>
+            </x-ui.table.row>
+        @endforelse
+    </x-ui.table.rows>
+</x-ui.table>
+```
+
+### Multiple Actions
+
+Provide users with multiple paths forward:
+
+@blade
+<x-demo class="w-full flex justify-center">
+    <div class="w-full max-w-lg">
+        <x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+            <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+                <x-ui.icon name="folder-plus" class="size-6" />
+            </x-ui.empty.media>
+            <!--  -->
+            <x-ui.empty.contents class="mt-auto">
+                <x-ui.heading>No projects yet</x-ui.heading>
+                <x-ui.text class="opacity-70">
+                    Create your first project or import an existing one.
+                </x-ui.text>
+                <div class="flex gap-2 mt-4">
+                    <x-ui.button size="sm">New project</x-ui.button>
+                    <x-ui.button variant="outline" size="sm">Import</x-ui.button>
+                </div>
+            </x-ui.empty.contents>
+        </x-ui.empty>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+    <x-ui.empty.media class="flex items-center justify-center w-12 h-12 rounded-full bg-neutral-100 dark:bg-neutral-800">
+        <x-ui.icon name="folder-plus" class="size-6" />
+    </x-ui.empty.media>
+
+    <x-ui.empty.contents>
+        <x-ui.heading>No projects yet</x-ui.heading>
+        <x-ui.text class="opacity-70">
+            Create your first project or import an existing one.
+        </x-ui.text>
+
+        <div class="flex gap-2 mt-4">
+            <x-ui.button size="sm">New project</x-ui.button>
+            <x-ui.button variant="outline" size="sm">Import</x-ui.button>
+        </div>
+    </x-ui.empty.contents>
+</x-ui.empty>
+```
+
+## Common Styling Patterns
+
+Here are some frequently used styling combinations:
+
+```blade
+<!-- Bordered card -->
+<x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box">
+
+<!-- Elevated card -->
+<x-ui.empty class="border border-neutral-200 dark:border-neutral-800 rounded-box shadow-sm">
+
+<!-- Filled background -->
+<x-ui.empty class="bg-neutral-50 dark:bg-neutral-900 rounded-box">
+
+<!-- Filled with border -->
+<x-ui.empty class="bg-neutral-50 dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-800 rounded-box">
+
+<!-- Subtle gradient background -->
+<x-ui.empty class="bg-gradient-to-b from-neutral-50 to-white dark:from-neutral-900 dark:to-neutral-950 rounded-box">
+
+<!-- Larger padding -->
+<x-ui.empty class="py-16">
+
+<!-- Icon container with color -->
+<x-ui.empty.media class="flex items-center justify-center w-14 h-14 rounded-full bg-blue-100 dark:bg-blue-900/20 text-blue-600 dark:text-blue-400">
+    <x-ui.icon name="inbox" class="size-7" />
+</x-ui.empty.media>
+```
\ No newline at end of file
diff --git a/components/input/files/index.blade.php b/components/input/files/index.blade.php
index 0c1b898..3db6665 100644
--- a/components/input/files/index.blade.php
+++ b/components/input/files/index.blade.php
@@ -47,7 +47,7 @@
     $iconCount = count(array_filter([$clearable, $copyable, $revealable, $rightIcon]));
 @endphp
 
-<div {{ $attributes->class(Arr::toCssClasses($classes)) }}>
+<div class="{{ Arr::toCssClasses(array_merge($classes, [$attributes->get('class')])) }}">
     {{-- HANDLE PREFIX SLOTS --}}
     @if (filled($prefix) || filled($prefixIcon))
         <x-ui.input.extra-slot data-slot="input-prefix">
@@ -190,7 +190,7 @@ class="!text-neutral-500 dark:!text-neutral-500"
         <input
             @class([
                 'z-10',
-                'inline-block border p-2 w-full text-base sm:text-sm text-neutral-800 disabled:text-neutral-500 placeholder-neutral-400 disabled:placeholder-neutral-400/70 dark:text-neutral-300 dark:disabled:text-neutral-400 dark:placeholder-neutral-400 dark:disabled:placeholder-neutral-500',
+                'inline-block border p-2 w-full text-sm text-neutral-800 disabled:text-neutral-500 placeholder-neutral-400 disabled:placeholder-neutral-400/70 dark:text-neutral-300 dark:disabled:text-neutral-400 dark:placeholder-neutral-400 dark:disabled:placeholder-neutral-500',
                 'bg-white dark:bg-neutral-900 dark:disabled:bg-neutral-800',
                 'disabled:cursor-not-allowed transition-colors duration-200',
                 'shadow-none dark:shadow-sm disabled:shadow-none rounded-box',
@@ -201,7 +201,7 @@ class="!text-neutral-500 dark:!text-neutral-500"
             name="{{ $name }}"
             type="{{ $type }}"
             data-slot="control"
-            {{ $attributes }}
+            {{ $attributes->except('class') }}
             data-control-id="input" {{-- used for actions --}}
             @if($invalid) invalid @endif
         />
diff --git a/components/otp/usage.md b/components/otp/usage.md
index 213369a..ea17b7d 100644
--- a/components/otp/usage.md
+++ b/components/otp/usage.md
@@ -505,30 +505,3 @@ The component includes comprehensive accessibility features:
 | `otp-complete` | `{ code: string }` | Fired when all inputs are filled |
 | `otp-clear` | - | Clears all inputs (listen with window) |
 | `otp-focus` | - | Focuses first empty input (listen with window) |
-
-## Technical Notes
-
-### Livewire Integration
-- Uses `Livewire.hook('morphed')` to handle DOM diffing
-- Refreshes `data-order` attributes after each morph
-- Supports both regular and `.live` model bindings
-- State synchronization happens automatically
-
-### Browser Compatibility
-- Works across Chrome, Firefox, Safari, and Edge
-- Uses `requestAnimationFrame()` for consistent focus behavior
-- Firefox-specific workarounds for `select()` timing issues
-
-### Performance
-- Minimal re-renders with smart state management
-- Uses `$nextTick()` to prevent race conditions
-- Efficient DOM queries with cached input references
-
-### Edge Cases Handled
-- Partial paste content
-- Invalid character filtering
-- Multi-character input (takes last character)
-- Clicking disabled inputs (::after overlay trick)
-- Livewire morph attribute stripping
-- External state changes (SSR-safe)
-- Delete key treated as backspace for consistency
diff --git a/components/pagination/usage.md b/components/pagination/usage.md
new file mode 100644
index 0000000..b593455
--- /dev/null
+++ b/components/pagination/usage.md
@@ -0,0 +1,207 @@
+---
+name: 'pagination'
+---
+
+# Pagination Component
+
+## Introduction
+
+The `pagination` component provides a flexible, accessible navigation system for paginated data. Built on top of Laravel's pagination system, it automatically detects whether you're using simple pagination or length-aware pagination and renders the appropriate interface. With two visual variants and full Livewire integration, it seamlessly handles user navigation through large datasets.
+
+## Installation
+
+Use the [sheaf artisan command](/docs/guides/cli-installation#content-component-management) to install the `pagination` component:
+```bash
+php artisan sheaf:install pagination
+```
+
+> Once installed, you can use the `<x-ui.pagination />` component in any Livewire component.
+
+## Basic Usage
+
+@blade
+<x-md.cta                                                            
+    href="/demos/pagination"                                    
+    label="See the interactive demo for this component"
+    ctaLabel="Go to Demo"
+/>
+@endblade
+
+### With Length-Aware Pagination
+
+Length-aware pagination provides page numbers and total count, ideal for datasets where users need to know the total number of pages.
+```php
+use Src\Components\Livewire\Concerns\WithPagination;
+
+class UsersTable extends Component
+{
+    use WithPagination;
+
+    public function render()
+    {
+        return view('livewire.users-table', [
+            'users' => User::paginate($this->perPage)
+        ]);
+    }
+}
+```
+```blade
+<!-- In your view -->
+<div>
+    @foreach($users as $user)
+        <div>{{ $user->name }}</div>
+    @endforeach
+
+    <x-ui.pagination :paginator="$users" />
+</div>
+```
+
+### With Simple Pagination
+
+Simple pagination only shows Previous/Next buttons without total page count, optimized for large datasets where counting all records would be expensive.
+```php
+public function render()
+{
+    return view('livewire.users-table', [
+        'users' => User::simplePaginate($this->perPage)
+    ]);
+}
+```
+```blade
+<!-- Same view code works automatically -->
+<x-ui.pagination :paginator="$users" />
+```
+
+> **Note:** The component automatically detects whether you're using `paginate()` or `simplePaginate()` and renders the appropriate interface.
+
+## Pagination Variants
+
+### Default Variant
+
+Compact pagination with minimal UI on the right corner for **simple** and **length-aware** paginations. No loading indicators.
+
+@blade
+<x-md.cta                                                            
+    href="/demos/pagination?variant=default"                                    
+    label="Look under the table section to see how pagination looks. Play around with controls to demo all 4 UI variations."
+    ctaLabel="Visit The Demo"
+/>
+@endblade
+
+### Full Variant
+
+Comprehensive pagination with item counts, page information, and per-page selector (for length-aware only). Expands to full width for simple pagination. Includes loading indicators.
+
+**Features:**
+- Shows "1-15 of 150" item range
+- Displays "Page 1 of 10"
+- Includes per-page selector (10, 20, 30...)
+- First/Last page buttons
+
+@blade
+<x-md.cta                                                            
+    href="/demos/pagination?variant=full"                                    
+    label="Look under the table section to see how pagination looks. Play around with controls to demo all 4 UI variations."
+    ctaLabel="Visit The Demo"
+/>
+@endblade
+
+## Usage with Table Component
+
+The pagination component integrates seamlessly with the table component.
+
+### Basic Integration
+```blade
+<x-ui.table :paginator="$users">
+    <x-ui.table.header>
+        <x-ui.table.columns>
+            <x-ui.table.head>Name</x-ui.table.head>
+            <x-ui.table.head>Email</x-ui.table.head>
+        </x-ui.table.columns>
+    </x-ui.table.header>
+
+    <x-ui.table.rows>
+        @foreach($users as $user)
+            <x-ui.table.row>
+                <x-ui.table.cell>{{ $user->name }}</x-ui.table.cell>
+                <x-ui.table.cell>{{ $user->email }}</x-ui.table.cell>
+            </x-ui.table.row>
+        @endforeach
+    </x-ui.table.rows>
+</x-ui.table>
+```
+
+> **Tip:** When you pass `:paginator` to the table component, it automatically renders pagination at the bottom. No need to add `<x-ui.pagination>` separately!
+
+### Specifying Pagination Variant
+
+Control the pagination variant through the table component:
+```blade
+<x-ui.table 
+    :paginator="$users" 
+    pagination:variant="full"
+>
+    <!-- Table content -->
+</x-ui.table>
+```
+
+## Customization
+
+### Per-Page Options
+
+Customize the available per-page options (default: 10, 20, 30, 40, 50):
+```blade
+<!-- Standalone pagination -->
+<x-ui.pagination 
+    :paginator="$users" 
+    :options="[10, 20, 30]" 
+    variant="full" 
+/>
+
+<!-- With table component -->
+<x-ui.table 
+    :paginator="$users" 
+    pagination:variant="full"
+    :pagination:options="[10, 20, 30]"
+>
+    <!-- Table content -->
+</x-ui.table>
+```
+
+> **Note:** The `$perPage` property defaults to 15. It's only interactive (user-changeable) when using length-aware pagination with the `full` variant, which includes a per-page selector.
+
+### Reset Pagination on Filter Change
+```php
+use Src\Components\Livewire\Concerns\WithPagination;
+
+class UsersTable extends Component
+{
+    use WithPagination;
+
+    public string $searchQuery = '';
+
+    public function updatedSearchQuery()
+    {
+        $this->resetPage(); // Reset to page 1 when search changes
+    }
+
+    public function render()
+    {
+        $users = User::query()
+            ->when($this->searchQuery, fn($q) => 
+                $q->where('name', 'like', "%{$this->searchQuery}%")
+            )
+            ->paginate($this->perPage);
+
+        return view('livewire.users-table', ['users' => $users]);
+    }
+}
+```
+
+## Component Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `paginator` | `Paginator\|LengthAwarePaginator\|CursorPaginator` | `null` | Laravel paginator instance (required) |
+| `variant` | `string` | `'default'` | Visual variant: `'default'` or `'full'` |
+| `options` | `array` | `[10, 20, 30, 40, 50]` | Per-page options (full variant only) |
\ No newline at end of file
diff --git a/components/select/files/index.blade.php b/components/select/files/index.blade.php
index 95976c3..d8151eb 100644
--- a/components/select/files/index.blade.php
+++ b/components/select/files/index.blade.php
@@ -267,7 +267,6 @@ function(){
      }}
 >
 
-     {{-- for classic form submission if your using livewire remove this sh**t --}}
     @if ($name)
         <input 
             type="hidden" 
diff --git a/components/skeleton/config.yml b/components/skeleton/config.yml
new file mode 100644
index 0000000..73574d3
--- /dev/null
+++ b/components/skeleton/config.yml
@@ -0,0 +1,4 @@
+files:
+  abstract: resources/views/components/ui/skeleton/abstract.blade.php
+  index: resources/views/components/ui/skeleton/index.blade.php
+  text: resources/views/components/ui/skeleton/text.blade.php
\ No newline at end of file
diff --git a/components/skeleton/files/abstract.blade.php b/components/skeleton/files/abstract.blade.php
new file mode 100644
index 0000000..375da2d
--- /dev/null
+++ b/components/skeleton/files/abstract.blade.php
@@ -0,0 +1,31 @@
+@aware(['animate' => 'glow', 'speed' => 'normal'])
+
+@php
+    $wave = [
+        'relative overflow-hidden isolate',
+        'before:absolute before:inset-0 _before:bg-red-500 before:-translate-x-full',
+        'before:animate-[wave_1.5s_infinite_linear]',
+        match ($speed) {
+            'slow' => 'before:animate-[wave_3s_infinite_linear]',
+            'normal' => 'before:animate-[wave_2s_infinite_linear]',
+            'fast' => 'before:animate-[wave_1s_infinite_linear]',
+            default => 'before:animate-[wave_2s_infinite_linear]',
+        },
+        // the moving effect is a gradient color of neutral and trasnparent and  tweack it as you need...
+        'before:bg-gradient-to-r before:from-transparent 
+         before:via-neutral-400/40 dark:before:via-neutral-600/40 
+         before:to-transparent',
+    ];
+
+    $animationClasses = match ($animate) {
+        'wave' => $wave,
+        'glow' => [...$wave, 'animate-pulse'],
+        'pulse' => ['animate-pulse'],
+        'none' => [],
+        default => ['animate-pulse'],
+    };
+
+@endphp
+<div {{ $attributes->class($animationClasses) }}>
+    {{ $slot }}
+</div>
diff --git a/components/skeleton/files/index.blade.php b/components/skeleton/files/index.blade.php
new file mode 100644
index 0000000..4796f4b
--- /dev/null
+++ b/components/skeleton/files/index.blade.php
@@ -0,0 +1,12 @@
+@props(['animate' => 'glow', 'speed' => 'normal'])
+
+<x-ui.skeleton.abstract 
+    :attributes="$attributes->class([
+        '[:where(&)]:h-4 [:where(&)]:rounded-md',
+        '[:where(&)]:bg-[--alpha(var(--color-neutral-400)_/_20%)]',
+        'dark:[:where(&)]:bg-[--alpha(var(--color-neutral-600)_/_20%)]',
+    ])" 
+    data-slot="skeleton"
+>
+    {{ $slot }}
+</x-ui.skeleton.abstract>
diff --git a/components/skeleton/files/text.blade.php b/components/skeleton/files/text.blade.php
new file mode 100644
index 0000000..6edeabb
--- /dev/null
+++ b/components/skeleton/files/text.blade.php
@@ -0,0 +1,21 @@
+@props(['animate' => 'glow', 'size' => 'base', 'speed' => 'normal'])
+
+
+@php
+    $sizeClasses = match ($size) {
+        'sm' => '[:where(&)]:h-4 py-[3px]',
+        'base' => '[:where(&)]:h-5 py-[3px]',
+        'lg' => '[:where(&)]:h-6 py-[2px]',
+        'xl' => '[:where(&)]:h-8 py-[2px]',
+        default => '[:where(&)]:h-5 py-[3px]',
+    };
+@endphp
+
+<x-ui.skeleton.abstract 
+    :attributes="$attributes->class([
+        '[:where(&)]:w-full flex',
+        '[:where(&)]:rounded-field',
+        $sizeClasses
+    ])" 
+    data-skeleton
+/>
diff --git a/components/skeleton/usage.md b/components/skeleton/usage.md
new file mode 100644
index 0000000..e74be95
--- /dev/null
+++ b/components/skeleton/usage.md
@@ -0,0 +1,328 @@
+---
+name: skeleton
+---
+
+## Introduction
+
+The `Skeleton` component provides **loading placeholders** that mimic the structure of your content while data is being fetched. It offers multiple animation styles and a flexible API for creating custom loading states that match your UI perfectly.
+
+## Installation
+
+Use the [sheaf artisan command](/docs/guides/cli-installation#content-component-management) to install the `skeleton` component easily:
+
+```bash
+php artisan sheaf:install skeleton
+```
+
+
+then add this css to your `app.css`:
+```css
+@keyframes wave {
+    0% {
+        transform: translateX(0%);
+    }
+
+    100% {
+        transform: translateX(200%);
+    }
+}
+```
+> Once installed, you can use the `<x-ui.skeleton />` and `<x-ui.skeleton.text />` components in any Blade view.
+
+## Usage
+
+@blade
+<x-demo class="flex justify-center">
+    <div class="w-xl space-y-4">
+        <x-ui.skeleton class="h-8 w-40" />
+        <x-ui.skeleton class="h-4 w-full" />
+        <x-ui.skeleton class="h-4 w-5/6" />
+        <x-ui.skeleton class="h-4 w-4/6" />
+    </div>
+</x-demo>
+@endblade
+
+### Basic Skeleton
+
+The most basic usage is a simple placeholder with custom dimensions:
+
+```blade
+<x-ui.skeleton class="h-8 w-40" />
+<x-ui.skeleton class="h-4 w-full" />
+<x-ui.skeleton class="size-12 rounded-full" />
+```
+
+## Animation Variants
+
+Choose from different animation styles to match your design preference:
+
+@blade
+<x-demo class="flex justify-center">
+    <div class="w-full max-w-3xl space-y-6">
+        <div class="space-y-2">
+            <p class="text-sm font-medium text-neutral-600 dark:text-neutral-400">Pulse </p>
+            <x-ui.skeleton animate="pulse" class="h-8 w-80" />
+        </div>
+        <div class="space-y-2">
+            <p class="text-sm font-medium text-neutral-600 dark:text-neutral-400">Wave</p>
+            <x-ui.skeleton animate="wave" class="h-8 w-80" />
+        </div>
+        <div class="space-y-2">
+            <p class="text-sm font-medium text-neutral-600 dark:text-neutral-400">Glow (wave + pulse)</p>
+            <x-ui.skeleton animate="glow" class="h-8 w-80" />
+        </div>
+        <div class="space-y-2">
+            <p class="text-sm font-medium text-neutral-600 dark:text-neutral-400">None</p>
+            <x-ui.skeleton animate="none" class="h-8 w-80" />
+        </div>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<!-- Pulse animation  -->
+<x-ui.skeleton animate="pulse" class="h-8 w-80" />
+
+<!-- Wave animation -->
+<x-ui.skeleton animate="wave" class="h-8 w-80" />
+
+<!-- Glow animation (default) -->
+<x-ui.skeleton animate="glow" class="h-8 w-80" />
+
+<!-- No animation -->
+<x-ui.skeleton animate="none" class="h-8 w-80" />
+```
+
+## Animation Speed
+
+@blade
+<x-demo class="flex justify-center">
+    <div class="w-full max-w-md space-y-6">
+        <div class="space-y-2">
+            <p class="text-sm font-medium text-neutral-600 dark:text-neutral-400">Slow </p>
+            <x-ui.skeleton speed="slow"  class="h-10 w-80" />
+        </div>
+        <div class="space-y-2">
+            <p class="text-sm font-medium text-neutral-600 dark:text-neutral-400">Normal</p>
+        <x-ui.skeleton speed="normal" class="h-10 w-80" />
+        </div>
+        <div class="space-y-2">
+            <p class="text-sm font-medium text-neutral-600 dark:text-neutral-400">Dast</p>
+          <x-ui.skeleton speed="fast" class="h-10 w-80" />
+        </div>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<!-- slow animation  -->
+<x-ui.skeleton speed="slow" speed class="h-10 w-80" />
+
+<!-- normal animation (default) -->
+<x-ui.skeleton speed="normal" class="h-10 w-80" />
+
+<!-- fast animation -->
+<x-ui.skeleton speed="fast" class="h-10 w-80" />
+```
+
+## Text Skeleton
+
+Use the `skeleton.text` component for text line placeholders with predefined heights:
+
+@blade
+<x-demo class="flex justify-center">
+    <div class="w-3xl space-y-4 " >
+        <div class="space-y-2">
+            <x-ui.skeleton.text size="sm"  />
+        </div>
+        <div class="space-y-2">
+            <x-ui.skeleton.text size="base" />
+        </div>
+        <div class="space-y-2">
+            <x-ui.skeleton.text size="lg" />
+        </div>
+        <div class="space-y-2">
+            <x-ui.skeleton.text size="xl" />
+        </div>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<!-- Small text -->
+<x-ui.skeleton.text size="sm" />
+
+<!-- Base text (default) -->
+<x-ui.skeleton.text />
+
+<!-- Large text -->
+<x-ui.skeleton.text size="lg" />
+
+<!-- Extra large text -->
+<x-ui.skeleton.text size="xl" />
+```
+
+## Examples
+
+
+### Card Skeleton
+
+Create complex loading states by combining skeleton components:
+
+@blade
+<x-demo class="flex justify-center">
+    <div class="w-full max-w-2xl rounded-box border border-neutral-200 dark:border-neutral-800 p-4 space-y-4">
+        <div class="flex items-center gap-3">
+            <x-ui.skeleton class="size-10 rounded-full" />
+            <div class="flex-1 space-y-2">
+                <x-ui.skeleton.text class="w-40" />
+                <x-ui.skeleton.text size="sm" class="w-24" />
+            </div>
+        </div>
+        <div class="space-y-2">
+            <x-ui.skeleton.text />
+            <x-ui.skeleton.text class="w-5/6" />
+        </div>
+        <x-ui.skeleton class="h-48 w-full rounded-box" />
+        <div class="flex gap-4 pt-2">
+            <x-ui.skeleton class="h-8 w-25 rounded-box" />
+            <x-ui.skeleton class="h-8 w-25 rounded-box" />
+        </div>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<div class="rounded-box border border-neutral-200 dark:border-neutral-800 p-4 space-y-4">
+    <!-- Header -->
+    <div class="flex items-center gap-3">
+        <x-ui.skeleton class="size-10 rounded-full" />
+        <div class="flex-1 space-y-2">
+            <x-ui.skeleton.text class="w-32" />
+            <x-ui.skeleton.text size="sm" class="w-24" />
+        </div>
+    </div>
+    
+    <!-- Content -->
+    <div class="space-y-2">
+        <x-ui.skeleton.text />
+        <x-ui.skeleton.text class="w-5/6" />
+    </div>
+    
+    <!-- Image -->
+    <x-ui.skeleton class="h-48 w-full rounded-box" />
+    
+    <!-- Actions -->
+    <div class="flex gap-4 pt-2">
+        <x-ui.skeleton class="h-8 w-20 rounded-box" />
+        <x-ui.skeleton class="h-8 w-20 rounded-box" />
+    </div>
+</div>
+```
+### Grid Skeleton
+
+For card grids and gallery layouts:
+
+@blade
+<x-demo class="flex justify-center">
+    <div class="w-4xl grid grid-cols-3 gap-4">
+        @foreach(range(1, 6) as $i)
+            <div class="space-y-3">
+                <x-ui.skeleton class="h-32 w-full rounded-box" />
+                <x-ui.skeleton.text class="w-3/4" />
+                <x-ui.skeleton.text size="sm" />
+            </div>
+        @endforeach
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<div class="grid grid-cols-3 gap-4">
+    @foreach(range(1, 6) as $i)
+        <div class="space-y-3">
+            <x-ui.skeleton class="h-48 w-full rounded-box" />
+            <x-ui.skeleton.text class="w-3/4" />
+            <x-ui.skeleton.text size="sm" />
+        </div>
+    @endforeach
+</div>
+```
+
+### Table Skeleton
+
+Use with tables and data grids:
+
+@blade
+<x-demo class="flex justify-center">
+    <div class="w-4xl max-w-4xl">
+        <table class="w-full">
+            <thead class="text-base font-normalt">
+                <tr>
+                <th>#</th>
+                <th>Number</th>
+                <th>Status</th>
+                <th>Punishments</th>
+                </tr>
+            </thead>
+            <tbody class="divide-y divide-neutral-200 dark:divide-neutral-800">
+                @foreach(range(1, 5) as $i)
+                    <tr>
+                        <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+                        <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+                        <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+                        <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+                    </tr>
+                @endforeach
+            </tbody>
+        </table>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<table class="w-full">
+     <thead class="text-base font-normalt">
+        <tr>
+            <th>#</th>
+            <th>Number</th>
+            <th>Status</th>
+            <th>Punishments</th>
+        </tr>
+    </thead>
+    <tbody class="divide-y divide-neutral-200 dark:divide-neutral-800">
+        @foreach(range(1, 5) as $i)
+            <tr>
+                <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+                <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+                <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+                <td class="px-4 py-3"><x-ui.skeleton.text /></td>
+            </tr>
+        @endforeach
+    </tbody>
+</table>
+```
+
+
+## Component Props
+
+#### Skeleton Component
+
+| Prop Name  | Type   | Default  | Required | Description                                              |
+| ---------- | ------ | -------- | -------- | -------------------------------------------------------- |
+| `animate`  | string | `'glow'` | No       | Animation style: `'pulse'`, `'wave'`, `'glow'`, `'none'` |
+
+#### Skeleton Text Component
+
+| Prop Name  | Type   | Default   | Required | Description                                              |
+| ---------- | ------ | --------- | -------- | -------------------------------------------------------- |
+| `animate`  | string | `'glow'`  | No       | Animation style: `'pulse'`, `'wave'`, `'glow'`, `'none'` |
+| `size`     | string | `'base'`  | No       | Text size: `'sm'`, `'base'`, `'lg'`, `'xl'`              |
+
+## Component Structure
+
+The skeleton component consists of:
+
+- **Base Component**: `<x-ui.skeleton>` - Generic skeleton placeholder
+- **Text Component**: `<x-ui.skeleton.text>` - Text line placeholder with size variants
+- **Abstract Component**: `<x-ui.skeleton.abstract>` - Internal animation logic (not for direct use)
diff --git a/components/table/usage.md b/components/table/usage.md
new file mode 100644
index 0000000..971a314
--- /dev/null
+++ b/components/table/usage.md
@@ -0,0 +1,2404 @@
+---
+name: 'table'
+---
+
+# Table Component
+
+## Introduction
+
+The `table` component provides a powerful, composable system for building feature-rich data tables. Built with Livewire and Alpine.js, it offers pagination, sorting, searching, selection, bulk actions, column visibility controls, and more all with excellent accessibility and a clean, modern design.
+
+Our approach uses **composable traits** on the backend and **Blade components** on the frontend, giving you complete control over your table's structure and behavior while maintaining clean, reusable code.
+
+## Installation
+
+Use the [sheaf artisan command](/docs/guides/cli-installation#content-component-management) to install the `table` component:
+
+```bash
+php artisan sheaf:install data-table
+```
+
+## Basic Static Table
+
+Let's start with a simple static table without any dynamic features.
+
+@blade
+<x-demo class="w-full">
+    <x-ui.table>
+        <x-ui.table.header>
+            <x-ui.table.columns>
+                <x-ui.table.head>Name</x-ui.table.head>
+                <x-ui.table.head>Email</x-ui.table.head>
+                <x-ui.table.head>Role</x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+        <x-ui.table.rows>
+            <x-ui.table.row>
+                <x-ui.table.cell>Alice Johnson</x-ui.table.cell>
+                <x-ui.table.cell>alice@example.com</x-ui.table.cell>
+                <x-ui.table.cell>Admin</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row>
+                <x-ui.table.cell>Bob Smith</x-ui.table.cell>
+                <x-ui.table.cell>bob@example.com</x-ui.table.cell>
+                <x-ui.table.cell>Editor</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row>
+                <x-ui.table.cell>Carol White</x-ui.table.cell>
+                <x-ui.table.cell>carol@example.com</x-ui.table.cell>
+                <x-ui.table.cell>Viewer</x-ui.table.cell>
+            </x-ui.table.row>
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table>
+    <x-ui.table.header>
+        <x-ui.table.columns>
+            <x-ui.table.head>Name</x-ui.table.head>
+            <x-ui.table.head>Email</x-ui.table.head>
+            <x-ui.table.head>Role</x-ui.table.head>
+        </x-ui.table.columns>
+    </x-ui.table.header>
+
+    <x-ui.table.rows>
+        <x-ui.table.row>
+            <x-ui.table.cell>Alice Johnson</x-ui.table.cell>
+            <x-ui.table.cell>alice@example.com</x-ui.table.cell>
+            <x-ui.table.cell>Admin</x-ui.table.cell>
+        </x-ui.table.row>
+        <!-- More rows... -->
+    </x-ui.table.rows>
+</x-ui.table>
+```
+
+---
+
+## Sorting
+
+### Usage
+
+Add column sorting with visual indicators and flexible behavior. To enable sorting, first add the `App\Livewire\Concerns\WithSorting` trait to your Livewire component:
+
+```php
+{~
+use App\Models\User;
+use App\Livewire\Concerns\WithSorting;
+use App\Livewire\Concerns\WithPagination;
+
+class UsersTable extends Component
+{~}
+    {+
+    use WithSorting;+}
+
+    public function render()
+    {
+        $users = User::query()
+{+            ->when(filled($this->sortBy), function ($query) {
+                return $this->applySorting($query);
+            })+}
+            ->paginate();
+
+        return view('livewire.users-table', [
+            'users' => $users,
+        ]);
+    }
+}
+```
+
+The `$this->sortBy` and `$this->applySorting()` methods come from the `WithSorting` trait.
+
+In your table header view, mark sortable columns and pass the current sort state:
+
+```blade
+<x-ui.table.head
+{+    column="name"
+    sortable
+    :currentSortBy="$sortBy"
+    :currentSortDir="$sortDir"+}
+>
+    Name
+</x-ui.table.head>
+```
+
+**Key attributes:**
+- `column` — Database column name
+- `sortable` — Marks the column as sortable
+- `currentSortBy` and `currentSortDir` — Reactive Livewire properties tracking sort state
+
+> **Note:** If you want to restrict sorting on the backend, you can use the `sortableColumns()` method on the component class.
+
+### Sorting Variants
+
+There are two sorting variants:
+
+- **`default`** — Shows sorting icons on hover and cycles sorting on click
+- **`dropdown`** — Opens a menu where the user explicitly chooses the sorting direction
+
+```blade
+<x-ui.table.head
+{~    column="name"
+    sortable
+    :currentSortBy="$sortBy"
+    :currentSortDir="$sortDir"~}
+{+    variant="default" <!-- default -->+}
+    <!-- or -->
+{+    variant="dropdown"+}
+>
+    Name
+</x-ui.table.head>
+```
+
+You can see these variants in action on our interactive [Math Theorems demo](/demos/datatables). Sorting by year uses the dropdown variant, while mathematician and difficulty columns use the default variant.
+
+### Sorting Algorithm
+
+By default, sorting uses Eloquent’s native `orderBy` method.
+
+For advanced cases, you may override sorting per column by defining a custom sorting algorithm in your Livewire component using `sortUsingAlgorithm`.
+
+If a custom algorithm handles the active column, it is applied.
+If not, the system falls back automatically to the default SQL sorting.
+
+```php
+public function sortUsingAlgorithm($query, string $column, string $direction): ?Builder
+{
+    if ($column === 'status') {
+        return $query->orderByRaw("
+            CASE
+                WHEN status = 'in_dev' THEN 1
+                WHEN status = 'done' THEN 2
+                WHEN status = 'production' THEN 3
+            END {$direction}
+        ");
+    }
+
+    return null;
+}
+```
+**the contract**
+
+* Return a `Builder` when the column is handled.
+* Return `null` to delegate to the default sorter.
+
+---
+
+
+
+## Pagination
+
+Add pagination to your table by passing a Laravel paginator to the table component.
+
+First, create a Livewire component that uses the `App\Livewire\Concerns\WithPagination` trait:
+
+```php
+use App\Livewire\Concerns\WithPagination;
+
+class UsersTable extends Component
+{
+    use WithPagination;
+
+    public function render()
+    {
+        $users = User::query()
+{+            ->paginate();+}
+            // or (if using length-aware paginator with full variant)
+{+            ->paginate($this->perPage);+}
+
+        return view('livewire.users-table', [
+            'users' => $users,
+        ]);
+    }
+}
+```
+
+Then pass the paginator to the `paginator` prop in the view:
+
+```blade
+<x-ui.table 
+{+    :paginator="$users"+}
+>
+    <!-- table contents... -->
+</x-ui.table>
+```
+
+### More About Pagination
+
+@blade
+<x-md.cta                                                            
+    href="/docs/components/pagination"                                    
+    label="The pagination component has very detailed documentation and demos there"
+    ctaLabel="Visit Docs"
+/>
+@endblade
+
+---
+
+## Search
+
+Enable real-time search across your table data. To enable search, first add the `App\Livewire\Concerns\WithSearch` trait to your Livewire component:
+
+```php
+{~
+use App\Models\User;
+use App\Livewire\Concerns\WithSearch;
+use App\Livewire\Concerns\WithPagination;
+
+class UsersTable extends Component
+{~}
+    {+
+    use WithSearch;+}
+
+    public function render()
+    {
+        $users = User::query()
+{+            ->when(filled($this->searchQuery), function ($query) {
+                return $this->applySearch($query);
+            })+}
+            ->paginate();
+
+        return view('livewire.users-table', [
+            'users' => $users,
+        ]);
+    }
+
+{+    protected function applySearch($query)
+    {
+        return $query->where('name', 'like', '%'.$this->searchQuery.'%');
+    }+}
+}
+```
+
+The `applySearch()` method is where you define your search logic.
+
+Then bind an input to the search query:
+
+```blade
+<x-ui.input 
+    placeholder="Search..." 
+    leftIcon="magnifying-glass" 
+{+    wire:model.live="searchQuery" <!-- this is what's important -->+}
+/>
+```
+
+See the search implementation in the complete guide below for a real-world layout.
+
+---
+
+## Selection
+
+The component comes with all the logic you need to add row selection and "select all" functionality for handling bulk actions. To enable selection, first add the `App\Livewire\Concerns\WithSelection` trait to your Livewire component:
+
+```php
+{~
+use App\Models\User;
+use App\Livewire\Concerns\WithSelection;
+
+class UsersTable extends Component
+{~}
+    {+
+    use WithSelection;+}
+
+    public function render()
+    {
+        $users = User::query()->paginate();
+
+        // This is crucial - it tells us about the visible rows on the page
+{+        $this->visibleIds = $users->pluck('id')
+            ->map(fn ($id) => (string) $id)
+            ->toArray();+}
+
+        return view('livewire.users-table', [
+            'users' => $users,
+        ]);
+    }
+}
+```
+
+Then in the view, add `:checkboxId` to each `table.row` component to show the checkbox at the start of the row. To add "check all" functionality, add `withCheckAll` to the `table.columns` component:
+
+```blade
+<x-ui.table.columns
+{+    withCheckAll+}
+>
+    <!-- other head components -->
+</x-ui.table.columns>
+
+<!-- AND -->
+
+<x-ui.table.row 
+{+    :checkboxId="$user->id"+}
+    :key="$user->id"
+>
+    <!-- cells... -->
+</x-ui.table.row>
+```
+
+Now you can perform operations on the selected IDs like this:
+
+```php
+public function deleteSelected()
+{
+    User::query()->whereIn('id', $this->selectedIds)->delete();
+}
+
+public function archiveSelected()
+{
+    User::query()->whereIn('id', $this->selectedIds)->each->archive();
+}
+```
+
+---
+
+## Loading States
+
+Due to the nature of datatables being usually data-heavy, this component comes with a clean way to handle loading states.
+
+To enable loading indicators, just add `wire:loading` to the table component:
+
+```blade
+<x-ui.table 
+{+    wire:loading+}
+>
+    <!-- table content... -->
+</x-ui.table>
+```
+
+For convenience, we've made it easy to enable loading on sorting, searching, and pagination by passing them comma-separated to the `loadOn` prop:
+
+```blade
+<x-ui.table 
+{+    wire:loading
+    loadOn="pagination, search, sorting"+}
+>
+    <!-- table content... -->
+</x-ui.table>
+```
+
+To add other targets, you can use `wire:target` as you would in regular usage:
+
+```blade
+<x-ui.table 
+{+    wire:loading
+    wire:target="customAction, archiveSomething"+}
+>
+    <!-- table content... -->
+</x-ui.table>
+```
+
+## Ordering
+
+Ordering allows users to rearrange table rows visually and persist the new order on the backend.
+
+### Usage
+
+To enable row reordering, mark the table as reorderable.
+
+```blade
+<x-ui.table 
+{+    reorderable+}
+>
+    <!-- table contents -->
+</x-ui.table>
+```
+
+Each table row must expose its current order value. This value determines the row’s position.
+
+```blade
+<x-ui.table.rows>
+    @forelse($users as $user)
+        <x-ui.table.row 
+            :checkboxId="$user->id" 
+{+            :order="$user->order"+} 
+            :key="$user->id"
+        >
+            <!-- ... -->
+        </x-ui.table.row>
+    @endforelse
+</x-ui.table.rows>
+```
+
+When a row is moved, the table emits the moved item identifier and its target position.
+
+
+### Backend Handling
+
+By default, the table expects a `handleReordering` method on the Livewire component to persist changes.
+
+```php
+{~
+use App\Models\User;
+use App\Livewire\Concerns\WithSorting;
+use App\Livewire\Concerns\WithPagination;
+
+class UsersTable extends Component
+{~}
+    public function render()
+    {
+        $users = User::query()
+            ->when(filled($this->sortBy), function ($query) {
+                return $this->applySorting($query);
+            })
+            ->paginate();
+
+        return view('livewire.users-table', [
+            'users' => $users,
+        ]);
+    }
+
+{+    public function handleReordering($item, $position)
+    {
+        // save changes based on $item and $position
+    }+}
+}
+```
+
+If you prefer a different method name, update the `x-sort="$wire.handleReordering"` binding on `table.rows`.
+
+
+### Ordering Algorithm
+
+**Concept**
+
+The ordering system is based on a single invariant:
+
+> At any time, each row has a unique numeric `order` value.
+
+Reordering an item consists of moving it to a new position and shifting all affected rows accordingly.
+
+**Pseudo Algorithm**
+
+1. Fetch the moved item
+2. If the target position equals the current one, stop
+3. Temporarily move the item out of the ordering range
+4. Shift affected rows up or down
+5. Assign the target order to the moved item
+6. Commit atomically
+
+**Database Implementation Example**
+
+Below is implementation of this algorithm in db level.
+
+```php
+public const MAX_ORDER = 4294967295;
+
+public function reorderUsers(int $item, int $position)
+{
+    $user = $this->User::query()->findOrFail($item);
+
+    $this->move($user, $position);
+}
+
+protected function move($user, int $position): void
+{
+    DB::transaction(function () use ($user, $position) {
+        $oldOrder = $user->order;
+        $newOrder = $position;
+
+        if ($oldOrder === $newOrder) {
+            return;
+        }
+
+        // temporarily move out of range 
+        $user->update(['order' => self::MAX_ORDER]);
+
+        $min = min($oldOrder, $newOrder);
+        $max = max($oldOrder, $newOrder);
+
+        $isDraggedDown = $oldOrder < $newOrder;
+
+        $this->baseQuery()
+            ->whereBetween('order', [$min, $max])
+            ->where('id', '!=', $user->id)
+            ->update([
+                'order' => DB::raw('`order` '.($isDraggedDown ? '-1' : '+1')),
+            ]);
+
+        $user->update([
+            'order' => $newOrder,
+        ]);
+    });
+}
+```
+
+maybe there is better way? please let me.
+
+### Order Normalization
+
+Over time, deletes or interrupted updates can introduce gaps or inconsistencies.
+Normalization rebuilds the ordering sequence deterministically.
+
+```php
+public function arrange()
+{
+    DB::transaction(function () {
+        $order = 0;
+
+        foreach ($this->baseQuery()->orderBy('order')->get() as $user) {
+            $user->update(['order' => $order++]);
+        }
+    });
+}
+```
+
+This operation is optional but recommended for long lived datasets, you can randomly re-arrange after each re-order operation happens
+
+---
+
+## Stickiness
+
+Make columns or headers stick to the viewport while scrolling.
+
+### Sticky Header
+
+Keep the header visible while scrolling through long tables:
+
+@blade
+<x-demo class="w-full">
+    <x-ui.table class="max-h-64">
+        <x-ui.table.header sticky class="dark:bg-neutral-900 bg-white">
+            <x-ui.table.columns>
+                <x-ui.table.head>Product</x-ui.table.head>
+                <x-ui.table.head>Price</x-ui.table.head>
+                <x-ui.table.head>Stock</x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+        <x-ui.table.rows>
+            @for ($i = 1; $i <= 20; $i++)
+                <x-ui.table.row>
+                    <x-ui.table.cell>Product {{ $i }}</x-ui.table.cell>
+                    <x-ui.table.cell>${{ rand(10, 100) }}</x-ui.table.cell>
+                    <x-ui.table.cell>{{ rand(0, 50) }}</x-ui.table.cell>
+                </x-ui.table.row>
+            @endfor
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table class="max-h-96">
+    <x-ui.table.header sticky class="dark:bg-neutral-900 bg-white">
+        <x-ui.table.columns>
+            <x-ui.table.head>Product</x-ui.table.head>
+            <x-ui.table.head>Price</x-ui.table.head>
+        </x-ui.table.columns>
+    </x-ui.table.header>
+    
+    <!-- ... -->
+</x-ui.table>
+```
+
+### Sticky Column
+
+Make the first column stick when scrolling horizontally:
+
+@blade
+<x-demo>
+    <x-ui.table>
+        <x-ui.table.header class="dark:bg-neutral-900 bg-white">
+            <x-ui.table.columns>
+                <x-ui.table.head 
+                    sticky 
+                    class="dark:bg-neutral-900 bg-white"
+                >
+                    Name
+                </x-ui.table.head>
+                <x-ui.table.head>Email</x-ui.table.head>
+                <x-ui.table.head>Department</x-ui.table.head>
+                <x-ui.table.head>Location</x-ui.table.head>
+                <x-ui.table.head>Start Date</x-ui.table.head>
+                <x-ui.table.head>End Date</x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+        <x-ui.table.rows>
+            <x-ui.table.row>
+                <x-ui.table.cell 
+                    sticky 
+                    class="dark:bg-neutral-950 bg-neutral-50"
+                >
+                    Alice Johnson
+                </x-ui.table.cell>
+                <x-ui.table.cell>alice@company.com</x-ui.table.cell>
+                <x-ui.table.cell>Engineering</x-ui.table.cell>
+                <x-ui.table.cell>San Francisco, CA</x-ui.table.cell>
+                <x-ui.table.cell>2023-01-15</x-ui.table.cell>
+                <x-ui.table.cell>2029-01-15</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row>
+                <x-ui.table.cell 
+                    sticky 
+                    class="dark:bg-neutral-950 bg-neutral-50"
+                >
+                    Bob Smith
+                </x-ui.table.cell>
+                <x-ui.table.cell>bob@company.com</x-ui.table.cell>
+                <x-ui.table.cell>Marketing</x-ui.table.cell>
+                <x-ui.table.cell>New York, NY</x-ui.table.cell>
+                <x-ui.table.cell>2022-08-20</x-ui.table.cell>
+                <x-ui.table.cell>2028-08-20</x-ui.table.cell>
+            </x-ui.table.row>
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table.header sticky class="dark:bg-neutral-900 bg-white">
+    <x-ui.table.columns>
+        <x-ui.table.head 
+            sticky 
+            class="dark:bg-neutral-900 bg-white"
+        >
+            Name
+        </x-ui.table.head>
+        <!-- Other headers... -->
+    </x-ui.table.columns>
+</x-ui.table.header>
+
+<x-ui.table.rows>
+    <x-ui.table.row>
+        <x-ui.table.cell 
+            sticky 
+            class="dark:bg-neutral-950 bg-neutral-50"
+        >
+            Alice Johnson
+        </x-ui.table.cell>
+        <!-- Other cells... -->
+    </x-ui.table.row>
+</x-ui.table.rows>
+```
+
+> **Note:** When using sticky headers or columns, always apply a background color to prevent content overlap during scrolling.
+
+
+when you've enable `reorderable` feature with sticky columns, adding background color to rows will kill the animated opacity for the sticky cell, so it's better to add the background only if there is not a sorting happenings and you can do that easily by using `[body:not(.sorting)_&]:` as a variant there.
+
+```blade
+<x-ui.table.row 
+    :checkboxId="$theorem->id" 
+    :key="$theorem->id"
+>
+    <x-ui.table.cell 
+        sticky 
+{+        class="[body:not(.sorting)_&]:dark:bg-neutral-950 [body:not(.sorting)_&]:bg-neutral-50"+}
+    >
+        {{ $theorem->id }}
+    </x-ui.table.cell>
+    <!-- .... -->
+</x-ui.table.row>
+```
+---
+
+## Implementation Guide
+
+### Overview
+
+This guide walks you through building a polished, feature-rich data table using the table component alongside other utilities. We'll display a list of mathematical theorems, including their discovery year and the mathematicians behind them.
+
+@blade
+<x-md.cta                                                            
+    href="/demos/data-tables"                                    
+    label="in this guide we're going to build a powerful datatable demo"
+    ctaLabel="Visit the Demo"
+/>
+@endblade
+
+---
+
+@blade
+<x-md.image                                                            
+    src="/images/demos/light/table.png"                                    
+    dark-src="/images/demos/dark/table.png"                                    
+    alt="theorems table"                                               
+    caption="Theorems Data Table Demo"                                   
+/>
+@endblade
+
+---
+@blade
+<x-md.cta                                                            
+    href="/docs/components/table#content-guides-full-code-source"                                    
+    label="Just Read and understand I've assemble all the code at the end for the demo"
+    ctaLabel="Go Below to Full Code"
+/>
+@endblade
+
+### Setup Theorems Data
+
+First, create a `Theorem` model with fields: `id`, `name`, `mathematician`, `field`, `year_discovered`, `difficulty_level`, `is_proven`, `statement`, and `applications`. 
+
+For this demo, we use the Sushi package with an in-memory array model. Our `App\Models\Theorem` looks like this:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Sushi\Sushi;
+
+class Theorem extends Model
+{
+    use Sushi;
+
+    protected $casts = [
+        'year_discovered' => 'integer',
+        'difficulty_level' => 'integer',
+        'is_proven' => 'boolean',
+    ];
+
+    protected function getRows(): array
+    {
+        return [
+            ['id' => 1, 'name' => 'Pythagorean Theorem', 'mathematician' => 'Pythagoras', 'field' => 'Geometry', 'year_discovered' => -500, 'difficulty_level' => 2, 'is_proven' => true, 'statement' => 'In a right triangle, a² + b² = c²', 'applications' => 'Architecture, Navigation'],
+            ['id' => 2, 'name' => 'Fundamental Theorem of Calculus', 'mathematician' => 'Isaac Newton & Gottfried Leibniz', 'field' => 'Analysis', 'year_discovered' => 1666, 'difficulty_level' => 7, 'is_proven' => true, 'statement' => 'Links differentiation and integration', 'applications' => 'Physics, Engineering'],
+            // ... (rest of theorems)
+        ];
+    }
+}
+```
+
+> **Note:** This demo uses array-based models for simplicity. Your real application will use standard Laravel Eloquent models, but the integration remains the same regardless of data source.
+
+### Table with Pagination
+
+Add the `App\Livewire\Concerns\WithPagination` trait to your Livewire component to enable pagination:
+
+```php
+use App\Models\Theorem;
+use App\Livewire\Concerns\WithPagination;
+use Illuminate\Database\Eloquent\Builder;
+
+class Theorems extends Component
+{
+{+    use WithPagination;+}
+
+    public function render()
+    {
+{+        $theorems = $this->baseQuery()->paginate($this->perPage);+}
+
+        return view('livewire.theorems', [
+            'theorems' => $theorems,
+        ]);
+    }
+
+{+    protected function baseQuery(): Builder
+    {
+        return Theorem::query();
+    }+}
+}
+```
+
+**Key points:**
+- We use a custom `WithPagination` trait that extends Livewire's native pagination with a `$perPage` property and reactive updates
+- The `baseQuery()` method encapsulates the core query builder, making it reusable for sorting, filtering, and other operations in later steps
+
+The view integrates pagination and displays theorem details with badges and icons:
+
+```blade
+<x-ui.table 
+{+    :paginator="$theorems"+}
+{+    pagination:variant="full"+}
+>
+    <x-ui.table.header>
+        <x-ui.table.columns>
+            <x-ui.table.head>ID</x-ui.table.head>
+            <x-ui.table.head>Theorem</x-ui.table.head>
+            <x-ui.table.head>Mathematician</x-ui.table.head>
+            <x-ui.table.head>Field</x-ui.table.head>
+            <x-ui.table.head>Year</x-ui.table.head>
+            <x-ui.table.head>Difficulty</x-ui.table.head>
+            <x-ui.table.head>Status</x-ui.table.head>
+        </x-ui.table.columns>
+    </x-ui.table.header>
+
+    <x-ui.table.rows>
+        @forelse($theorems as $theorem)
+            <x-ui.table.row :key="$theorem->id">
+                <x-ui.table.cell sticky class="dark:bg-neutral-950 bg-neutral-50">
+                    {{ $theorem->id }}
+                </x-ui.table.cell>
+                
+                <x-ui.table.cell>
+                    <div class="max-w-xs">
+                        <div class="font-medium text-neutral-900 dark:text-neutral-100">
+                            {{ $theorem->name }}
+                        </div>
+                        <div class="text-xs text-neutral-500 dark:text-neutral-400 mt-1 line-clamp-2">
+                            {{ $theorem->statement }}
+                        </div>
+                    </div>
+                </x-ui.table.cell>
+                
+                <x-ui.table.cell>
+                    <div class="text-sm text-neutral-700 dark:text-neutral-300">
+                        {{ $theorem->mathematician }}
+                    </div>
+                </x-ui.table.cell>
+                
+                <x-ui.table.cell>
+                    @php
+                        $fieldColors = [
+                            'Number Theory' => 'purple',
+                            'Analysis' => 'blue',
+                            'Geometry' => 'green',
+                            // ... more field colors
+                        ];
+                        $color = $fieldColors[$theorem->field] ?? 'neutral';
+                    @endphp
+                    <x-ui.badge :color="$color" size="sm" variant="outline">
+                        {{ $theorem->field }}
+                    </x-ui.badge>
+                </x-ui.table.cell>
+                
+                <x-ui.table.cell>
+                    <div class="text-sm font-mono text-neutral-600 dark:text-neutral-400">
+                        {{ $theorem->year_discovered < 0 ? abs($theorem->year_discovered) . ' BC' : $theorem->year_discovered }}
+                    </div>
+                </x-ui.table.cell>
+                
+                <x-ui.table.cell>
+                    <div class="flex items-center gap-1">
+                        @for($i = 1; $i <= min($theorem->difficulty_level, 10); $i++)
+                            <svg class="size-3 {{ $i <= 3 ? 'text-green-500' : ($i <= 6 ? 'text-yellow-500' : 'text-red-500') }}" fill="currentColor" viewBox="0 0 20 20">
+                                <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.175 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81h3.461a1 1 0 00.951-.69l1.07-3.292z" />
+                            </svg>
+                        @endfor
+                    </div>
+                    <div class="text-xs text-neutral-500 dark:text-neutral-400 mt-1">
+                        Level {{ $theorem->difficulty_level }}
+                    </div>
+                </x-ui.table.cell>
+                
+                <x-ui.table.cell>
+                    @if($theorem->is_proven)
+                        <x-ui.badge icon="check-circle" color="green" size="sm" variant="outline">
+                            Proven
+                        </x-ui.badge>
+                    @else
+                        <x-ui.badge icon="exclamation-triangle" color="orange" size="sm" variant="outline">
+                            Conjecture
+                        </x-ui.badge>
+                    @endif
+                </x-ui.table.cell>
+            </x-ui.table.row>
+        @empty
+            <!-- to implement in upcoming section -->
+        @endforelse
+    </x-ui.table.rows>
+</x-ui.table>
+```
+
+### Add Sorting
+
+Enable column sorting with visual indicators and flexible behavior.
+
+#### Step 1: Add the Trait
+
+Include the `App\Livewire\Concerns\WithSorting` trait in your Livewire component:
+
+```php
+use App\Models\Theorem;
+use App\Livewire\Concerns\WithSorting;
+use App\Livewire\Concerns\WithPagination;
+
+class Theorems extends Component
+{
+{+    use WithSorting;+}
+    use WithPagination;
+
+    public function render()
+    {
+        $theorems = $this->baseQuery()
+{+            ->when(filled($this->sortBy), function ($query) {
+                return $this->applySorting($query);
+            })+}
+            ->paginate($this->perPage);
+
+        return view('livewire.theorems', [
+            'theorems' => $theorems,
+        ]);
+    }
+
+    protected function baseQuery(): Builder
+    {
+        return Theorem::query();
+    }
+}
+```
+
+#### Step 2: Update the View
+
+Let's make `mathematician`, `year`, and `difficulty` sortable, while making sort by year special by using the `dropdown` sorting variant:
+
+```blade
+<x-ui.table 
+    :paginator="$theorems"
+    pagination:variant="full"
+{+    loadOn="pagination, sorting"+}
+>
+    <x-ui.table.header>
+        <x-ui.table.columns>
+            <!-- other headers -->
+            <x-ui.table.head
+{+                column="mathematician"
+                sortable
+                :currentSortBy="$sortBy"
+                :currentSortDir="$sortDir"+}
+            >
+                Mathematician
+            </x-ui.table.head>
+            
+            <x-ui.table.head>
+                Field
+            </x-ui.table.head>
+            
+            <x-ui.table.head
+{+                column="year_discovered"
+                sortable
+                variant="dropdown"
+                :currentSortBy="$sortBy"
+                :currentSortDir="$sortDir"+}
+            >
+                Year
+            </x-ui.table.head>
+            
+            <x-ui.table.head
+{+                column="difficulty_level"
+                sortable
+                :currentSortBy="$sortBy"
+                :currentSortDir="$sortDir"+}
+            >
+                Difficulty
+            </x-ui.table.head>
+            
+            <x-ui.table.head>
+                Status
+            </x-ui.table.head>
+        </x-ui.table.columns>
+    </x-ui.table.header>
+    
+    <!-- table rows... -->
+</x-ui.table>
+```
+
+### Add Search
+
+Enable real-time search across your table data.
+
+#### Step 1: Add the Trait
+
+Include the `WithSearch` trait:
+
+```php
+<?php
+
+namespace App\Livewire;
+
+use App\Models\Theorem;
+use Livewire\Component;
+use App\Livewire\Concerns\WithPagination;
+use App\Livewire\Concerns\WithSorting;
+use App\Livewire\Concerns\WithSearch;
+
+class Theorems extends Component
+{
+    use WithPagination;
+    use WithSorting;
+{+    use WithSearch;+}
+
+    public function render()
+    {
+        $theorems = $this->baseQuery()
+            ->when(filled($this->sortBy), function ($query) {
+                return $this->applySorting($query);
+            })
+{+            ->when(filled($this->searchQuery), function ($query) {
+                return $this->applySearch($query);
+            })+}
+            ->paginate($this->perPage);
+
+        return view('livewire.theorems', [
+            'theorems' => $theorems,
+        ]);
+    }
+
+{+    protected function applySearch($query)
+    {
+        return $query->where('name', 'like', '%'.$this->searchQuery.'%')
+            ->orWhere('mathematician', 'like', '%'.$this->searchQuery.'%')
+            ->orWhere('field', 'like', '%'.$this->searchQuery.'%')
+            ->orWhere('statement', 'like', '%'.$this->searchQuery.'%');
+    }+}
+
+    protected function baseQuery(): Builder
+    {
+        return Theorem::query();
+    }
+}
+```
+
+#### Step 2: Add the Search Input
+
+First, let's wrap our table and all filter logic into the `table.container` Blade component, which is responsible for managing padding between pagination, table, and filters in a clean way:
+
+```blade
+{+<x-ui.table.container>+}
+{+    <div class="flex items-center">
+        {{-- SEARCH INPUT --}}
+        <div class="ml-auto">
+            <x-ui.input 
+                class="[&_input]:bg-transparent" <!-- target underlying input and make it transparent -->
+                placeholder="Search..." 
+                leftIcon="magnifying-glass" 
+                wire:model.live="searchQuery"
+            />
+        </div>
+    </div>+}
+
+    <x-ui.table 
+        :paginator="$theorems"
+        pagination:variant="full"
+{+        loadOn="pagination, search, sorting"+}
+    >
+        <!-- table contents... -->
+    </x-ui.table>
+{+</x-ui.table.container>+}
+```
+
+### Handle Empty States
+
+Provide helpful feedback when no results are found using our [empty state component](/docs/components/empty):
+
+@blade
+<x-demo>
+    <x-ui.table>
+        <x-ui.table.header>
+        </x-ui.table.header>
+        <x-ui.table.rows>
+            <x-ui.table.empty>
+                <x-ui.empty>
+                    <x-ui.empty.media>
+                        <x-ui.icon name="inbox" class="size-10" />
+                    </x-ui.empty.media>
+
+                    <x-ui.empty.contents>
+                        <h3 class="text-lg font-semibold">No theorems found</h3>
+                        <p class="text-sm text-neutral-500">
+                            Try adjusting your search or filters.
+                        </p>
+                    </x-ui.empty.contents>
+                </x-ui.empty>
+            </x-ui.table.empty>
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+
+
+```blade
+<x-ui.table.rows>
+    @forelse ($theorems as $user)
+       <!-- hidden contents -->
+    @empty
+{+      <x-ui.table.empty>
+            <x-ui.empty>
+                <x-ui.empty.media>
+                    <x-ui.icon name="inbox" class="size-10" />
+                </x-ui.empty.media>
+                <x-ui.empty.contents>
+                    <h3 class="text-lg font-semibold">No theorems found</h3>
+                    <p class="text-sm text-neutral-500">
+                        Try adjusting your search or create a new user.
+                    </p>
+                </x-ui.empty.contents>
+            </x-ui.empty>
+        </x-ui.table.empty>+}
+    @endforelse
+</x-ui.table.rows>
+```
+
+### Add Checkbox Selection
+
+Enable row selection with checkboxes and a "select all" header.
+
+#### Step 1: Add the Trait
+
+Include the `WithSelection` trait:
+
+```php
+<?php
+
+namespace App\Livewire;
+
+use App\Models\Theorem;
+use Livewire\Component;
+use App\Livewire\Concerns\WithPagination;
+use App\Livewire\Concerns\WithSorting;
+use App\Livewire\Concerns\WithSearch;
+use App\Livewire\Concerns\WithSelection;
+
+class Theorems extends Component
+{
+{~    use WithPagination;
+    use WithSorting;
+    use WithSearch;~}
+{+    use WithSelection;+}
+
+    public function render()
+    {
+        $theorems = $this->baseQuery()->...();
+
+        // Store visible IDs for "select all" functionality
+{+        $this->visibleIds = $theorems->pluck('id')
+            ->map(fn ($id) => (string) $id)
+            ->toArray();+}
+
+        return view('livewire.theorems', [
+            'theorems' => $theorems,
+        ]);
+    }
+}
+```
+
+#### Step 2: Add Checkboxes to the View
+
+Enable the "check all" header and add checkboxes to rows:
+
+```blade
+<x-ui.table.columns 
+{+    withCheckAll+}
+>
+    <!-- header cells... -->
+</x-ui.table.columns>
+
+<!-- AND -->
+
+<x-ui.table.rows>
+    @foreach ($theorems as $theorem)
+        <x-ui.table.row 
+            :key="$theorem->id"
+{+            :checkboxId="$theorem->id"+}
+        >
+            <!-- cells... -->
+        </x-ui.table.row>
+    @endforeach
+</x-ui.table.rows>
+```
+
+### Bulk Actions (Delete and CSV Export Example)
+
+Let's add bulk action buttons that only show when there are selected rows. We'll implement delete and CSV export for the selected rows.
+
+#### Step 1: Add the CSV Export Trait
+
+Include the `CanExportCsv` trait:
+
+```php
+<?php
+
+namespace App\Livewire;
+
+use App\Livewire\Concerns\CanExportCsv;
+use Livewire\Attributes\Renderless;
+
+class Theorems extends Component
+{
+{~    use WithPagination;
+    use WithSorting;
+    use WithSearch;
+    use WithSelection;~}
+{+    use CanExportCsv;+}
+
+{+    #[Renderless]
+    public function exportSelected()
+    {
+        $theorems = $this->baseQuery();
+        
+        if (filled($this->selectedIds)) {
+            $theorems = $theorems->whereIn('id', $this->selectedIds);
+        }
+        
+        // Apply filters like search and sorting if you want
+        // then convert them into CSV...
+        return $this->csv($theorems->get());
+    }+}
+
+{+    public function deleteSelected()
+    {
+        // ⚠️ Don't forget validation & authorization
+
+        // Gate::authorize('delete-theorem', Theorem::class);
+        
+        $this->baseQuery()
+            ->whereIn('id', $this->selectedIds)
+            ->delete();
+
+        // You may clear selection after deletes
+        $this->deselectAll();
+    }+}
+
+    // other methods...
+}
+```
+
+#### Step 2: Add Bulk Actions UI
+
+Add bulk action controls that appear when rows are selected:
+
+```blade
+<x-ui.table.container>
+    <div class="flex items-center">
+{+        {{-- BULK ACTIONS --}}
+        <div
+            style="display:none;" 
+            wire:show="selectedIds.length"
+        >
+            <x-ui.dropdown position="bottom-start">
+                <x-slot:button class="justify-center">
+                    <!-- desktop button -->
+                    <x-ui.button 
+                        icon="ellipsis-vertical" 
+                        variant="soft"
+                        size="sm"
+                        class="
+                            rounded-box mr-2 [@media(width<40rem)]:hidden outline 
+                            dark:outline-white/20 outline-neutral-900/10 
+                            dark:ring-white/15 ring-neutral-900/15 
+                            [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm
+                        " 
+                    >
+                        Bulk Actions
+                    </x-ui.button>
+                    
+                    <!-- mobile button (icon only) -->
+                    <x-ui.button 
+                        icon="ellipsis-vertical" 
+                        variant="soft"
+                        size="sm"
+                        class="
+                            rounded-box mr-2 sm:hidden outline dark:outline-white/20
+                            outline-neutral-900/10 dark:ring-white/15 ring-neutral-900/15 
+                            [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm
+                        " 
+                    />
+                </x-slot:button>
+                
+                <x-slot:menu>
+                    <x-ui.dropdown.item 
+                        icon="arrow-down-on-square"
+                        wire:click="exportSelected"
+                    >
+                        Export Selected CSV
+                    </x-ui.dropdown.item>
+                    
+                    <x-ui.dropdown.item 
+                        icon="trash"
+                        variant="danger"
+                        wire:click="deleteSelected"
+                        wire:confirm="Are you sure you want to delete?"
+                    >
+                        Delete Selected
+                    </x-ui.dropdown.item>
+                </x-slot:menu>
+            </x-ui.dropdown>
+        </div>+}
+
+        {{-- SEARCH INPUT --}}
+        <div class="ml-auto">
+            <x-ui.input 
+                class="[&_input]:bg-transparent"
+                placeholder="Search..." 
+                leftIcon="magnifying-glass" 
+                wire:model.live="searchQuery"
+            />
+        </div>
+    </div>
+    
+    <x-ui.table ...>
+        <!-- table content... -->
+    </x-ui.table>
+</x-ui.table.container>
+```
+
+### Add Column Visibility
+
+Let's make status and difficulty hideable columns in our theorems table. Here's how:
+
+@blade
+<x-demo>
+    <div x-data="{ hiddenCols: [] }">
+        <div class="mb-4 flex justify-end">
+            <x-ui.dropdown
+                checkbox
+                checkboxVariant
+                position="bottom-end"
+            >
+                <x-slot:button>
+                    <x-ui.button 
+                        icon="view-columns" 
+                        variant="soft"
+                        size="sm"
+                        class="rounded-box ml-2 outline dark:outline-white/20 outline-neutral-900/10 dark:ring-white/15 ring-neutral-900/15 [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm" 
+                    />
+                </x-slot:button>
+                
+                <x-slot:menu>                        
+                    <x-ui.dropdown.item readOnly>
+                        Hidden Columns
+                    </x-ui.dropdown.item> 
+                    <x-ui.dropdown.separator/> 
+                    <x-ui.dropdown.item value="difficulty" x-model="hiddenCols">
+                        Difficulty
+                    </x-ui.dropdown.item> 
+                    <x-ui.dropdown.item value="status" x-model="hiddenCols">
+                        Status
+                    </x-ui.dropdown.item> 
+                </x-slot:menu>
+            </x-ui.dropdown>
+        </div>
+        
+        <x-ui.table>
+            <x-ui.table.header>
+                <x-ui.table.columns>
+                    <x-ui.table.head>#ID</x-ui.table.head>
+                    <x-ui.table.head>Theorem</x-ui.table.head>
+                    <x-ui.table.head>Mathematician</x-ui.table.head>
+                    <x-ui.table.head>Field</x-ui.table.head>
+                    <x-ui.table.head>Year</x-ui.table.head>
+                    <x-ui.table.head x-show="!hiddenCols.includes('difficulty')" x-cloak>
+                        Difficulty
+                    </x-ui.table.head>
+                    <x-ui.table.head x-show="!hiddenCols.includes('status')" x-cloak>
+                        Status
+                    </x-ui.table.head>
+                </x-ui.table.columns>
+            </x-ui.table.header>
+            
+            <x-ui.table.rows>
+                <x-ui.table.row>
+                    <x-ui.table.cell>1</x-ui.table.cell>
+                    <x-ui.table.cell>Fundamental Theorem of Calculus</x-ui.table.cell>
+                    <x-ui.table.cell>Isaac Newton & Gottfried Leibniz</x-ui.table.cell>
+                    <x-ui.table.cell>
+                        <x-ui.badge color="blue" variant="outline">
+                            Analysis
+                        </x-ui.badge>
+                    </x-ui.table.cell>
+                    <x-ui.table.cell>1666</x-ui.table.cell>
+                    <x-ui.table.cell x-show="!hiddenCols.includes('difficulty')" x-cloak>
+                        7
+                    </x-ui.table.cell>
+                    <x-ui.table.cell x-show="!hiddenCols.includes('status')" x-cloak>
+                        <x-ui.badge color="green" variant="outline">
+                            Proven
+                        </x-ui.badge>
+                    </x-ui.table.cell>
+                </x-ui.table.row>
+                
+                <x-ui.table.row>
+                    <x-ui.table.cell>2</x-ui.table.cell>
+                    <x-ui.table.cell>Fermat's Last Theorem</x-ui.table.cell>
+                    <x-ui.table.cell>Andrew Wiles</x-ui.table.cell>
+                    <x-ui.table.cell>
+                        <x-ui.badge color="pink" variant="outline">
+                            Number Theory
+                        </x-ui.badge>
+                    </x-ui.table.cell>
+                    <x-ui.table.cell>1995</x-ui.table.cell>
+                    <x-ui.table.cell x-show="!hiddenCols.includes('difficulty')" x-cloak>
+                        10
+                    </x-ui.table.cell>
+                    <x-ui.table.cell x-show="!hiddenCols.includes('status')" x-cloak>
+                        <x-ui.badge color="green" variant="outline">
+                            Proven
+                        </x-ui.badge>
+                    </x-ui.table.cell>
+                </x-ui.table.row>
+            </x-ui.table.rows>
+        </x-ui.table>
+    </div>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table.container x-data="{ hiddenCols: ['status', 'difficulty'] }">
+    <div class="flex items-center">
+        <!-- BULK ACTIONS CONTENT... -->
+        <!-- SEARCH INPUT CONTENT... -->
+
+{+        {{-- HIDDEN COLUMNS --}}
+        <x-ui.dropdown
+            checkbox
+            checkboxVariant
+            position="bottom-end"
+        >
+            <x-slot:button>
+                <x-ui.button 
+                    icon="view-columns" 
+                    variant="soft"
+                    size="sm"
+                    class="rounded-box ml-2 outline dark:outline-white/20 outline-neutral-900/10 dark:ring-white/15 ring-neutral-900/15 [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm" 
+                />
+            </x-slot:button>
+            
+            <x-slot:menu>                        
+                <x-ui.dropdown.item readOnly>
+                    Hidden Columns
+                </x-ui.dropdown.item> 
+                <x-ui.dropdown.separator/> 
+                <x-ui.dropdown.item value="difficulty" x-model="hiddenCols">
+                    Difficulty
+                </x-ui.dropdown.item> 
+                <x-ui.dropdown.item value="status" x-model="hiddenCols">
+                    Status
+                </x-ui.dropdown.item> 
+            </x-slot:menu>
+        </x-ui.dropdown>+}
+    </div>
+    
+    <x-ui.table 
+        :paginator="$theorems"
+        pagination:variant="full"
+        loadOn="pagination, search, sorting"
+    >
+        <x-ui.table.header sticky class="dark:bg-neutral-900 bg-white">
+            <x-ui.table.columns withCheckAll>
+                <x-ui.table.head sticky class="dark:bg-neutral-900 bg-white">
+                    #ID
+                </x-ui.table.head>
+                <x-ui.table.head>Theorem</x-ui.table.head>
+                <x-ui.table.head
+                    column="mathematician"
+                    sortable
+                    :currentSortBy="$sortBy"
+                    :currentSortDir="$sortDir"
+                >
+                    Mathematician
+                </x-ui.table.head>
+                <x-ui.table.head>Field</x-ui.table.head>
+                <x-ui.table.head
+                    column="year_discovered"
+                    sortable
+                    variant="dropdown"
+                    :currentSortBy="$sortBy"
+                    :currentSortDir="$sortDir"
+                >
+                    Year
+                </x-ui.table.head>
+                <x-ui.table.head
+                    column="difficulty_level"
+                    sortable
+                    :currentSortBy="$sortBy"
+                    :currentSortDir="$sortDir"
+{+                    x-show="!hiddenCols.includes('difficulty')"+}
+                >
+                    Difficulty
+                </x-ui.table.head>
+                <x-ui.table.head  
+{+                    x-show="!hiddenCols.includes('status')"+}
+                >
+                    Status
+                </x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+
+        <x-ui.table.rows>
+            @forelse($theorems as $theorem)
+                <x-ui.table.row 
+                    :checkboxId="$theorem->id" 
+                    :key="$theorem->id"
+                >
+                    <!-- ID, Theorem, Mathematician, Field, Year cells... -->
+                    
+                    <x-ui.table.cell 
+{+                        x-show="!hiddenCols.includes('difficulty')"+}
+                    >
+                        <!-- difficulty stars -->
+                        <div class="text-xs text-neutral-500 dark:text-neutral-400 mt-1">
+                            Level {{ $theorem->difficulty_level }}
+                        </div>
+                    </x-ui.table.cell>
+                    
+                    <x-ui.table.cell  
+{+                        x-show="!hiddenCols.includes('status')"+}
+                    >
+                        @if($theorem->is_proven)
+                            <x-ui.badge icon="check-circle" color="green" size="sm" variant="outline">
+                                Proven
+                            </x-ui.badge>
+                        @else
+                            <x-ui.badge icon="exclamation-triangle" color="orange" size="sm" variant="outline">
+                                Conjecture
+                            </x-ui.badge>
+                        @endif
+                    </x-ui.table.cell>
+                </x-ui.table.row>
+            @empty
+                <!-- empty state... -->
+            @endforelse
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-ui.table.container>
+```
+
+#### Persisting Column Preferences
+
+Use Alpine's `$persist` plugin to save user preferences across sessions:
+
+```blade
+x-data="{ 
+    hiddenCols: $persist(['status', 'difficulty']).as('table-hidden-columns')
+}"
+```
+
+This stores the user's column visibility choices in `localStorage`.
+
+---
+
+### Adding Reordering
+To enable row reordering, mark the table as reorderable.
+
+```blade
+<x-ui.table 
+{+    reorderable+}
+>
+    <!-- table contents -->
+</x-ui.table>
+```
+
+Each table row must expose its current order value. This value determines the row’s position.
+
+```blade
+<x-ui.table.rows>
+    @forelse($users as $user)
+        <x-ui.table.row 
+            :checkboxId="$user->id" 
+{+            :order="$user->order"+} 
+            :key="$user->id"
+        >
+            <!-- ... -->
+        </x-ui.table.row>
+    @endforelse
+</x-ui.table.rows>
+```
+
+and let's implement the backend, in my case I going to use static array for orders to minize the complexity, but if you want real database example see the docs above.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+class Theorems extends Component
+{
+    // traits...
+
+{+    #[Session()]
+    public array $positions = [];+}
+{+
+    public function mount()
+    {
+        if (empty($this->positions)) {
+            $this->positions = $this->baseQuery()
+                ->pluck('id')
+                ->toArray();
+        }
+    }+}
+
+    public function render(): View
+    {
+        $theorems = $this->baseQuery()
+            ->when(filled($this->sortBy), function ($query) {
+                return $this->applySorting($query);
+            })
+            ->when(filled($this->searchQuery), function ($query) {
+                return $this->applySearch($query);
+            })
+{+            ->when(filled($this->positions), function ($query) {
+                return $this->applyPositionSorting($query);
+            })+}
+            ->paginate($this->perPage);
+        
+        // more stuff
+
+        return view('livewire.theorems', [
+            'theorems' => $theorems,
+        ]);
+    }
+
+   
+
+{+    public function handleReordering($item, $position)
+    {
+        $itemId = (int) $item;
+        // Remove item from current position
+        $positions = array_values(array_filter($this->positions, fn ($id) => $id !== $itemId));
+        // Insert at new position
+        array_splice($positions, $position, 0, [$itemId]);
+        $this->positions = $positions;
+    }+}
+
+{+    protected function applyPositionSorting(Builder $query): Builder
+    {
+        if (empty($this->positions)) {
+            return $query;
+        }
+        $case = 'CASE';
+        foreach ($this->positions as $index => $id) {
+            $case .= " WHEN id = {$id} THEN {$index}";
+        }
+        $case .= ' END';
+        return $query->orderByRaw($case);
+    }+}
+
+}
+
+```
+
+## Guide's Full Code Source 
+
+**Livewire/Theorems.php** livewire class component 
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Src\Components\Livewire\Demos;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\View\View;
+use Livewire\Attributes\Session;
+use Livewire\Component;
+use Livewire\Attributes\Renderless;
+use Src\Components\Livewire\Concerns\CanExportCsv;
+use Src\Components\Livewire\Concerns\WithPagination;
+use Src\Components\Livewire\Concerns\WithSearch;
+use Src\Components\Livewire\Concerns\WithSelection;
+use Src\Components\Livewire\Concerns\WithSorting;
+use Src\Components\Models\Theorem;
+
+class Theorems extends Component
+{
+    use CanExportCsv;
+    use WithPagination;
+    use WithSearch;
+    use WithSelection;
+    use WithSorting;
+
+    #[Session()]
+    public array $positions = [];
+
+    public function mount()
+    {
+        if (empty($this->positions)) {
+            $this->positions = $this->baseQuery()
+                ->pluck('id')
+                ->toArray();
+        }
+    }
+
+    public function render(): View
+    {
+        $theorems = $this->baseQuery()
+            ->when(filled($this->sortBy), function ($query) {
+                return $this->applySorting($query);
+            })
+            ->when(filled($this->searchQuery), function ($query) {
+                return $this->applySearch($query);
+            })
+            ->when(filled($this->positions), function ($query) {
+                return $this->applyPositionSorting($query);
+            })
+            ->paginate($this->perPage);
+
+        $this->visibleIds = $this->baseQuery()->pluck('id')->map(fn ($id) => (string) $id)->toArray();
+
+        usleep(500 * 1000);
+
+        return view('livewire.theorems', [
+            'theorems' => $theorems,
+        ]);
+    }
+
+    #[Renderless]
+    public function toCsv()
+    {
+        $theorems = $this->baseQuery();
+
+        if (filled($this->searchQuery)) {
+            $theorems = $this->applySearch($theorems);
+        }
+
+        if (filled($this->sortBy)) {
+            $theorems = $this->applySorting($theorems);
+        }
+
+        if (filled($this->selectedIds)) {
+            $theorems = $this->applySelection($theorems);
+        }
+
+        return $this->csv($theorems->get());
+    }
+
+    public function handleReordering($item, $position)
+    {
+        $itemId = (int) $item;
+
+        // Remove item from current position
+        $positions = array_values(array_filter($this->positions, fn ($id) => $id !== $itemId));
+
+        // Insert at new position
+        array_splice($positions, $position, 0, [$itemId]);
+
+        $this->positions = $positions;
+    }
+
+    public function deleteSelected()
+    {
+        $this->baseQuery()->whereIn('id',$this->selectedIds)->delete()
+    }
+
+    protected function applyPositionSorting(Builder $query): Builder
+    {
+        if (empty($this->positions)) {
+            return $query;
+        }
+
+        $case = 'CASE';
+
+        foreach ($this->positions as $index => $id) {
+            $case .= " WHEN id = {$id} THEN {$index}";
+        }
+
+        $case .= ' END';
+
+        return $query->orderByRaw($case);
+    }
+
+    protected function baseQuery(): Builder
+    {
+        return Theorem::query();
+    }
+
+    protected function applySearch($query)
+    {
+        return $query->where('name', 'like', '%'.$this->searchQuery.'%')
+            ->orWhere('mathematician', 'like', '%'.$this->searchQuery.'%')
+            ->orWhere('field', 'like', '%'.$this->searchQuery.'%')
+            ->orWhere('statemen', 'like', '%'.$this->searchQuery.'%');
+    }
+}
+
+```
+
+**livewire/theorems.blade.php** livewire blade component
+
+```blade
+<div class="min-h-screen py-12 px-4 ">
+    <div class="md:sticky top-20 w-fit ">
+        <x-ui.theme-switcher variant="inline"/>
+    </div>
+        
+    <div class="max-w-6xl mx-auto space-y-8">
+         <!-- Header -->
+        <div class="text-center space-y-2 border border-dashed dark:border-white/15 border-neutral-950/35 py-6 rounded-box mb-20">
+            <h1 class="text-3xl font-bold text-neutral-900 dark:text-white">
+                Datatable Component
+            </h1>
+            <p class="text-neutral-600 dark:text-neutral-400">
+                Interactive demos for Datatable component capabilitites
+            </p>
+        </div>
+
+        <x-ui.table.container x-data="{ hiddenCols: ['status', 'difficulty'] }">
+            <div 
+                class="flex items-center"
+            >
+                {{-- BULK ACTIONS --}}
+                <div
+                    style="display:none;" 
+                    wire:show="selectedIds.length"
+                >
+                    <x-ui.dropdown position="bottom-start">
+                        <x-slot:button class="justify-center">
+                            <x-ui.button 
+                                icon="ellipsis-vertical" 
+                                variant="soft"
+                                size="sm"
+                                class="rounded-box mr-2 [@media(width<40rem)]:hidden outline dark:outline-white/20 outline-neutral-900/10 dark:ring-white/15 ring-neutral-900/15 [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm" 
+                            >
+                                bulk action
+                            </x-ui.button>
+                            
+                            <x-ui.button 
+                                icon="ellipsis-vertical" 
+                                variant="soft"
+                                size="sm"
+                                class="rounded-box mr-2 sm:hidden outline dark:outline-white/20 outline-neutral-900/10 dark:ring-white/15 ring-neutral-900/15 [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm" 
+                            />
+                        </x-slot:button>
+                        
+                        <x-slot:menu>
+                            <x-ui.dropdown.item 
+                                icon="arrow-down-on-square"
+                                wire:click="toCsv"
+                            >
+                                export selected csv
+                            </x-ui.dropdown.item>
+                            
+                            <x-ui.dropdown.item 
+                                icon="trash"
+                                variant="danger"
+                                wire:click="deleteSelected"
+                                wire:confirm="are you sure you want to delete ?"
+                            >
+                                delete selected
+                            </x-ui.dropdown.item>
+                        </x-slot:menu>
+                    </x-ui.dropdown>
+                </div>
+
+                {{-- SEARCH INPUT --}}
+                <div class="ml-auto">
+                    <x-ui.input 
+                        class="[&_input]:bg-transparent"  
+                        placeholder="search..." 
+                        leftIcon="magnifying-glass" 
+                        wire:model.live="searchQuery"
+                    />
+                </div>
+
+                {{-- FILTERS AND HIDDEN COLUMNS --}}
+                <x-ui.dropdown
+                    checkbox
+                    checkboxVariant
+                    position="bottom-end"
+                >
+                    <x-slot:button>
+                        <x-ui.button 
+                            icon="view-columns" 
+                            variant="soft"
+                            size="sm"
+                            class="rounded-box ml-2 outline dark:outline-white/20 outline-neutral-900/10 dark:ring-white/15 ring-neutral-900/15 [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm" 
+                        />
+                    </x-slot:button>
+                    
+                    <x-slot:menu>                        
+                        <x-ui.dropdown.item readOnly>
+                            hidden columns
+                        </x-ui.dropdown.item> 
+                        <x-ui.dropdown.separator/> 
+                        <x-ui.dropdown.item 
+                            x-model="hiddenCols" 
+                        >
+                            difficulty
+                        </x-ui.dropdown.item> 
+                        <x-ui.dropdown.item 
+                            x-model="hiddenCols" 
+                        >
+                            status
+                        </x-ui.dropdown.item> 
+                    </x-slot:menu>
+                </x-ui.dropdown>
+                <x-ui.dropdown
+                    checkbox
+                    checkboxVariant
+                    position="bottom-end"
+                >
+                    <x-slot:button>
+                        <x-ui.button 
+                            icon="funnel" 
+                            variant="soft"
+                            size="sm"
+                            class="rounded-box ml-2 outline dark:outline-white/20 outline-neutral-900/10 dark:ring-white/15 ring-neutral-900/15 [[data-open]>&]:bg-white/5 [[data-open]>&]:ring-2 shadow-sm" 
+                        />
+                    </x-slot:button>
+                    
+                    <x-slot:menu>                        
+                        <x-ui.dropdown.item readOnly>
+                            Date Range
+                        </x-ui.dropdown.item> 
+                        <x-ui.dropdown.separator/> 
+                        <x-ui.dropdown.item>
+                            dificulty
+                        </x-ui.dropdown.item> 
+                    </x-slot:menu>
+                </x-ui.dropdown>
+            </div>
+            <!-- Demo Table -->
+            <x-ui.table 
+                :paginator="$paginator"  
+                pagination:variant="full"
+                wire:loading
+                reorderable
+                loadOn="pagination, search, sorting"
+            >
+                <x-ui.table.header sticky class="dark:bg-neutral-900 bg-white">
+                    <x-ui.table.columns withCheckAll>
+                        <x-ui.table.head sticky class="dark:bg-neutral-900 bg-white">
+                            #ID
+                        </x-ui.table.head>
+                        <x-ui.table.head>
+                            Theorem
+                        </x-ui.table.head>
+                        <x-ui.table.head
+                            column="mathematician"
+                            sortable
+                            :currentSortBy="$sortBy"
+                            :currentSortDir="$sortDir"
+                        >
+                            Mathematician
+                        </x-ui.table.head>
+                        <x-ui.table.head>
+                            Field
+                        </x-ui.table.head>
+                        <x-ui.table.head
+                            column="year_discovered"
+                            sortable
+                            variant="dropdown"
+                            :currentSortBy="$sortBy"
+                            :currentSortDir="$sortDir"
+                        >
+                            Year
+                        </x-ui.table.head>
+                        <x-ui.table.head
+                            column="difficulty_level"
+                            sortable
+                            :currentSortBy="$sortBy"
+                            :currentSortDir="$sortDir"
+                            x-show="!hiddenCols.includes('difficulty')" x-cloak
+                        >
+                            Difficulty
+                        </x-ui.table.head>
+                        <x-ui.table.head  
+                            x-show="!hiddenCols.includes('status')" x-cloak
+                        >
+                            Status
+                        </x-ui.table.head>
+                    </x-ui.table.columns>
+                </x-ui.table.header>
+
+                <x-ui.table.rows>
+                    @forelse($paginator as $theorem)
+                        <x-ui.table.row 
+                            :checkboxId="$theorem->id" 
+                            :order="$theorem->id" 
+                            :key="$theorem->id"
+                        >
+                            <x-ui.table.cell sticky class="[body:not(.sorting)_&]:dark:bg-neutral-950 [body:not(.sorting)_&]:bg-neutral-50">
+                                {{ $theorem->id }}
+                            </x-ui.table.cell>
+                            <x-ui.table.cell>
+                                <div class="max-w-xs">
+                                    <div class="font-medium text-neutral-900 dark:text-neutral-100">
+                                        {{ $theorem->name }}
+                                    </div>
+                                    <div class="text-xs text-neutral-500 dark:text-neutral-400 mt-1 line-clamp-2">
+                                        {{ $theorem->statement }}
+                                    </div>
+                                </div>
+                            </x-ui.table.cell>
+                            
+                            <x-ui.table.cell>
+                                <div class="text-sm text-neutral-700 dark:text-neutral-300">
+                                    {{ $theorem->mathematician }}
+                                </div>
+                            </x-ui.table.cell>
+                            
+                            <x-ui.table.cell>
+                                @php
+                                    $fieldColors = [
+                                        'Number Theory' => 'purple',
+                                        'Analysis' => 'blue',
+                                        'Geometry' => 'green',
+                                        'Algebra' => 'red',
+                                        'Topology' => 'orange',
+                                        'Probability' => 'pink',
+                                        'Complex Analysis' => 'cyan',
+                                        'Functional Analysis' => 'indigo',
+                                        'Vector Calculus' => 'teal',
+                                        'Game Theory' => 'violet',
+                                        'Graph Theory' => 'lime',
+                                        'Logic' => 'amber',
+                                        'Linear Algebra' => 'rose',
+                                        'Set Theory' => 'fuchsia',
+                                        'Mathematical Physics' => 'sky',
+                                        'Complexity Theory' => 'emerald',
+                                    ];
+                                    $color = $fieldColors[$theorem->field] ?? 'neutral';
+                                @endphp
+                                <x-ui.badge :color="$color" size="sm" variant="outline">
+                                    {{ $theorem->field }}
+                                </x-ui.badge>
+                            </x-ui.table.cell>
+                            
+                            <x-ui.table.cell>
+                                <div class="text-sm font-mono text-neutral-600 dark:text-neutral-400">
+                                    {{ $theorem->year_discovered < 0 ? abs($theorem->year_discovered) . ' BC' : $theorem->year_discovered }}
+                                </div>
+                            </x-ui.table.cell>
+                            
+                            <x-ui.table.cell 
+                                x-show="!hiddenCols.includes('difficulty')" x-cloak
+                            >
+                                <div class="flex items-center gap-1">
+                                    @for($i = 1; $i <= min($theorem->difficulty_level, 10); $i++)
+                                        <svg class="size-3 {{ $i <= 3 ? 'text-green-500' : ($i <= 6 ? 'text-yellow-500' : 'text-red-500') }}" fill="currentColor" viewBox="0 0 20 20">
+                                            <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.175 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81h3.461a1 1 0 00.951-.69l1.07-3.292z" />
+                                        </svg>
+                                    @endfor
+                                </div>
+                                <div class="text-xs text-neutral-500 dark:text-neutral-400 mt-1">
+                                    Level {{ $theorem->difficulty_level }}
+                                </div>
+                            </x-ui.table.cell>
+                            
+                            <x-ui.table.cell  
+                                x-show="!hiddenCols.includes('status')" x-cloak
+                            >
+                                @if($theorem->is_proven)
+                                    <x-ui.badge icon="check-circle" color="green" size="sm" variant="outline">
+                                        Proven
+                                    </x-ui.badge>
+                                @else
+                                    <x-ui.badge icon="exclamation-triangle" color="orange" size="sm" variant="outline">
+                                        Conjecture
+                                    </x-ui.badge>
+                                @endif
+                            </x-ui.table.cell>
+                        </x-ui.table.row>
+                    @empty
+                        <x-ui.table.empty>
+                            <x-ui.empty>
+                                <x-ui.empty.media>
+                                    <x-ui.icon name="inbox" class="size-10" />
+                                </x-ui.empty.media>
+                                <x-ui.empty.contents>
+                                    <h3 class="text-lg font-semibold">No theorems found</h3>
+                                    <p class="text-sm text-neutral-500">
+                                        The mathematical universe seems empty!
+                                    </p>
+                                </x-ui.empty.contents>
+                            </x-ui.empty>
+                        </x-ui.table.empty>
+                    @endforelse
+                </x-ui.table.rows>
+            </x-ui.table>
+        </x-ui.table.container>
+
+    </div>
+</div>
+```
+
+## Design Cookbook
+
+Customize the table's appearance with utility classes and variants.
+
+### Bordered Table
+
+@blade
+<x-demo class="w-full">
+    <x-ui.table class="border border-neutral-200 dark:border-neutral-800 rounded-lg">
+        <x-ui.table.header>
+            <x-ui.table.columns>
+                <x-ui.table.head>Product</x-ui.table.head>
+                <x-ui.table.head>Price</x-ui.table.head>
+                <x-ui.table.head>Stock</x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+
+        <x-ui.table.rows>
+            <x-ui.table.row>
+                <x-ui.table.cell>Widget A</x-ui.table.cell>
+                <x-ui.table.cell>$29.99</x-ui.table.cell>
+                <x-ui.table.cell>45</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row>
+                <x-ui.table.cell>Widget B</x-ui.table.cell>
+                <x-ui.table.cell>$39.99</x-ui.table.cell>
+                <x-ui.table.cell>12</x-ui.table.cell>
+            </x-ui.table.row>
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table class="border border-neutral-200 dark:border-neutral-800 rounded-lg">
+    <!-- Table content... -->
+</x-ui.table>
+```
+if you have dynamic data table, it recomended to add the border to the table container and let's the container manager the padding between pagination, filters, and the actual table data.
+
+just add the border prop to the container, you may tweack it on the container source code, the code is yours
+
+```blade
+<x-ui.table.container border>
+    <div 
+        class="flex items-center"
+    >
+        <!-- dynamic filters... -->
+    </div>
+
+    <!-- Demo Table -->
+    <x-ui.table >
+    <!-- table contents -->
+    </x-ui.table >
+</x-ui.table.container>
+```
+
+
+### Striped Rows
+
+@blade
+<x-demo class="w-full">
+    <x-ui.table>
+        <x-ui.table.header>
+            <x-ui.table.columns>
+                <x-ui.table.head>Name</x-ui.table.head>
+                <x-ui.table.head>Email</x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+
+        <x-ui.table.rows class="[&>tr:nth-child(odd)]:bg-neutral-50 dark:[&>tr:nth-child(odd)]:bg-neutral-900/50">
+            <x-ui.table.row>
+                <x-ui.table.cell>Alice Johnson</x-ui.table.cell>
+                <x-ui.table.cell>alice@example.com</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row>
+                <x-ui.table.cell>Bob Smith</x-ui.table.cell>
+                <x-ui.table.cell>bob@example.com</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row>
+                <x-ui.table.cell>Carol White</x-ui.table.cell>
+                <x-ui.table.cell>carol@example.com</x-ui.table.cell>
+            </x-ui.table.row>
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table.rows class="[&>tr:nth-child(odd)]:bg-neutral-50 dark:[&>tr:nth-child(odd)]:bg-neutral-900/50">
+    <!-- Rows... -->
+</x-ui.table.rows>
+```
+
+### Hover Effects
+
+@blade
+<x-demo class="w-full">
+    <x-ui.table>
+        <x-ui.table.header>
+            <x-ui.table.columns>
+                <x-ui.table.head>Name</x-ui.table.head>
+                <x-ui.table.head>Status</x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+
+        <x-ui.table.rows>
+            <x-ui.table.row class="hover:bg-neutral-100 dark:hover:bg-neutral-800 transition-colors cursor-pointer">
+                <x-ui.table.cell>Alice Johnson</x-ui.table.cell>
+                <x-ui.table.cell>Active</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row class="hover:bg-neutral-100 dark:hover:bg-neutral-800 transition-colors cursor-pointer">
+                <x-ui.table.cell>Bob Smith</x-ui.table.cell>
+                <x-ui.table.cell>Active</x-ui.table.cell>
+            </x-ui.table.row>
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+```blade
+<x-ui.table.row class="hover:bg-neutral-100 dark:hover:bg-neutral-800 transition-colors cursor-pointer">
+    <!-- Cells... -->
+</x-ui.table.row>
+```
+
+### Compact Table
+
+@blade
+<x-demo class="w-full">
+    <x-ui.table>
+        <x-ui.table.header>
+            <x-ui.table.columns>
+                <x-ui.table.head class="py-2">Name</x-ui.table.head>
+                <x-ui.table.head class="py-2">Email</x-ui.table.head>
+            </x-ui.table.columns>
+        </x-ui.table.header>
+
+        <x-ui.table.rows>
+            <x-ui.table.row>
+                <x-ui.table.cell class="py-2">Alice Johnson</x-ui.table.cell>
+                <x-ui.table.cell class="py-2">alice@example.com</x-ui.table.cell>
+            </x-ui.table.row>
+            <x-ui.table.row>
+                <x-ui.table.cell class="py-2">Bob Smith</x-ui.table.cell>
+                <x-ui.table.cell class="py-2">bob@example.com</x-ui.table.cell>
+            </x-ui.table.row>
+        </x-ui.table.rows>
+    </x-ui.table>
+</x-demo>
+@endblade
+
+```blade
+<!-- Override cell padding for compact layout -->
+<x-ui.table.cell class="py-2">
+    {{ $theorem->name }}
+</x-ui.table.cell>
+```
+
+### Custom Loading States
+
+```blade
+<x-ui.table 
+    :paginator="$theorems"
+    wire:loading
+    loadOn="pagination, search, sorting"
+>
+    <x-slot name="loading">
+        <div class="flex items-center gap-2">
+            <x-ui.icon.loading class="size-5" />
+            <span class="text-sm">Loading data...</span>
+        </div>
+    </x-slot>
+    
+    <!-- Table content... -->
+</x-ui.table>
+```
+
+---
+
+## Component Props
+
+### table
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `paginator` | Paginator\|null | `null` | Laravel paginator instance |
+| `pagination:variant` | string | `'full'` | Pagination style: `full`, `simple`, `compact` |
+| `loadOn` | string | `null` | Comma-separated list of actions to show loading: `pagination`, `search`, `sorting` |
+| `loading` | slot | `null` | Custom loading indicator |
+| `footer` | slot | `null` | Content below the table |
+| `wire:loading` | boolean | `false` | Enable Livewire loading states |
+| `wire:target` | string | `null` | Specific Livewire actions to track |
+| `class` | string | `''` | Additional CSS classes |
+
+### table.container
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `border` | boolean | `true` | Show container border |
+| `class` | string | `''` | Additional CSS classes |
+
+### table.header
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sticky` | boolean | `false` | Make header stick to top while scrolling |
+| `class` | string | `''` | Additional CSS classes |
+
+### table.columns
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `withCheckAll` | boolean | `false` | Add "select all" checkbox in header |
+
+### table.head
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `column` | string\|null | `null` | Column name for sorting |
+| `sortable` | boolean | `false` | Enable sorting for this column |
+| `variant` | string | `'default'` | Sorting UI: `default`, `dropdown` |
+| `currentSortBy` | string | `''` | Current sort column |
+| `currentSortDir` | string | `''` | Current sort direction |
+| `sticky` | boolean | `false` | Make column stick while scrolling horizontally |
+| `class` | string | `''` | Additional CSS classes |
+
+### table.row
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `key` | string\|null | `null` | Unique key for Livewire tracking |
+| `checkboxId` | string\|int\|null | `null` | ID for checkbox selection |
+| `class` | string | `''` | Additional CSS classes |
+
+### table.cell
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sticky` | boolean | `false` | Make cell stick while scrolling horizontally |
+| `class` | string | `''` | Additional CSS classes |
+
+### Common Patterns
+
+**Reset All Filters**
+```php
+public function resetAll()
+{
+    $this->searchQuery = '';
+    $this->sortBy = '';
+    $this->sortDir = 'asc';
+    $this->selectedIds = [];
+    $this->resetPage();
+}
+```
+
+**Export All vs Selected**
+```php
+public function export($exportType = 'selected')
+{
+    $query = $this->baseQuery();
+    
+    if ($exportType === 'selected' && filled($this->selectedIds)) {
+        $query->whereIn('id', $this->selectedIds);
+    }
+    
+    // Apply current filters/search
+    if (filled($this->searchQuery)) {
+        $query = $this->applySearch($query);
+    }
+
+    .....
+    
+    return $this->csv($query->get());
+}
+```
+
+## Troubleshooting
+
+### Checkboxes Not Syncing
+
+Ensure you're setting `visibleIds` in your render method:
+
+```php
+public function render()
+{
+    $theorems = Theorem::query()->paginate($this->perPage);
+    
+    // This is crucial for checkbox sync
+    $this->visibleIds = $theorems->pluck('id')
+        ->map(fn ($id) => (string) $id)
+        ->toArray();
+        
+    return view('livewire.theorems', ['theorems' => $theorems]);
+}
+```
+
+
+## Related Components
+
+- [Pagination](/docs/components/pagination) - Standalone pagination component
+- [Dropdown](/docs/components/dropdown) - Used for bulk actions and filters
+- [Input](/docs/components/input) - Used for search fields
+- [Checkbox](/docs/components/checkbox) - Used for row selection
+- [Empty State](/docs/components/empty) - Used when no results found
\ No newline at end of file
diff --git a/components/tabs/files/index.blade.php b/components/tabs/files/index.blade.php
index ff9e242..e5510d6 100644
--- a/components/tabs/files/index.blade.php
+++ b/components/tabs/files/index.blade.php
@@ -18,13 +18,13 @@
             'data-[active=true]:border',
         ],
         'non-contained' => [
-            'data-[active=true]:bg-neutral-900/10 dark:data-[active=true]:bg-white/10',
+            'data-[active=true]:bg-neutral-900/10 dark:data-[active=true]:bg-white/10 text-neutral-900 dark:text-neutral-50',
             'hover:bg-white/10 focus:bg-white/10', // focus and hover
             'rounded-[calc(var(--noncontained-variant-radius)-var(--noncontained-variant-padding))]', // those variables are defined on the group wrapper
         ],
         'pills' => [
             'rounded-full h-8 whitespace-nowrap rounded-full text-sm font-medium',
-            'data-[active=true]:bg-primary data-[active=true]:text-primary-fg'
+            'data-[active=true]:bg-(--color-primary) data-[active=true]:text-(--color-primary-fg)'
         ],
         default => [],
     };
diff --git a/components/tabs/files/panel.blade.php b/components/tabs/files/panel.blade.php
index 4b087a8..6c2a26b 100644
--- a/components/tabs/files/panel.blade.php
+++ b/components/tabs/files/panel.blade.php
@@ -1,25 +1,19 @@
 @aware(['variant' => 'outlined'])
 
 @props([
-    'name' => null
+    'name' => null,
 ])
 @php
-$classes = match($variant){
-    'outlined' => [
-        'border border-black/10 dark:border-white/10 rounded-box',
-        'bg-white p-3 dark:bg-neutral-800',
-    ],
-    'non-contained' => ['mt-2'],
-    default => []
+    $classes = match ($variant) {
+        'outlined' => ['border border-black/10 dark:border-white/10 rounded-box ', 'bg-white p-3 dark:bg-neutral-800'],
+        'non-contained' => ['mt-2'], // it's non contained broo, panels had freedom here.
+    default => [],
 };
+$classes = ['text-start text-neutral-900 dark:text-neutral-50', ...$classes];
 @endphp
 
-<div
-    {{ $attributes->class($classes) }}
-    data-slot="tabs-panel"
-    style="display:none;"
-    @if(filled($name))data-name="{{ $name }}"@endif
-    x-show="isActive({ name: @js($name), index: $el.dataset.panelOrder });"
->
+<div {{ $attributes->class($classes) }} data-slot="tabs-panel" style="display:none;"
+    @if (filled($name)) data-name="{{ $name }}" @endif
+    x-show="isActive({ name: @js($name), index: $el.dataset.panelOrder });">
     {{ $slot }}
 </div>
diff --git a/components/tabs/usage.md b/components/tabs/usage.md
index b504481..b0d4812 100644
--- a/components/tabs/usage.md
+++ b/components/tabs/usage.md
@@ -538,14 +538,6 @@ to push tabs to end **use `justify-end`**
 ```
 
 under the hood we check the presence of `justify-*` class, to handle some edge cases in some variants
-## Accessibility Features
-
-The tabs component includes full accessibility support:
-
-- **Keyboard Navigation**: Use arrow keys, Home, End, Page Up, and Page Down to navigate
-- **ARIA Attributes**: Proper `role="tablist"` and related ARIA attributes
-- **Focus Management**: Automatic focus management when switching tabs
-- **Screen Reader Support**: Proper labeling and state announcements
 
 ### Keyboard Shortcuts