+
+
+
Your messages will be backed up to Amazon Web Services.
- ...
+
+ Your messages will be backed up to Google Drive.
+
+
+
+
+
+ ...
+
+
+
+
+
+ Follow Michael K. Ocansey to know when they post any new articles and code snippets.
+
+
+ Follow Francis Appiah to know when they post any new articles and code snippets.
+
```
## Form Submission
-Checkable cards can be used within forms as a substitute for checkboxes or radio buttons. The `name` specified is what will be accessed when the form is submitted. Selecting multiple values results in a comma separated list being passed when the form is submitted.
-
-Using the **hosting** name from our examples above, after submitting the form the value of the hosting checkcards can be accessed using any of the following ways permitted in Laravel.
+Checkable cards substitute for checkboxes or radio buttons in a form. The `name` given is what's accessed on submission; selecting multiple values results in a comma-separated list.
-```blade
+```php
$request->get('hosting');
$request->input('hosting');
$request->hosting;
@@ -182,73 +162,72 @@ $request->hosting;
### Checkcards Component
-This is the parent tag for defining Checkcards.
+Parent tag for defining Checkcards.
| Attribute | Default | Description |
|---|---|---|
-| name | null | Name to be accessed when checkcard selections are submitted in a form. |
+| name | null | Name to access when checkcard selections are submitted in a form. |
| color | gray | `primary` \| `yellow` \| `green` \| `blue` \| `pink` \| `cyan` \| `purple` \| `gray` \| `orange` \| `indigo` \| `fuchsia` \| `violet` |
-| max | 1 | How many checkcards can be selected at a time. Any positive number > 0. |
-| required | false | Determines if checkcards are required when displayed in a form. `true` \| `false` |
-| selected_value | _(empty string)_ | In edit mode you will want selected checkcards to be selected by default. Set the values as a comma separated list. |
-| error_message | _(empty string)_ | Message to display when `max` is set and user selection exceeds the max allowed. |
-| error_heading | Error | Heading to display in the notification when displaying an error message. |
-| icon | null | Display an icon prefix. You can use any icon from Heroicons. |
-| avatar | null | Display an avatar as an image or label. If this is less than 4 characters, the avatar will be displayed as a label. |
-| avatar_size | medium | Determine size of the avatar to display. `tiny` \| `small` \| `medium` \| `regular` \| `big` \| `huge` \| `omg` |
-| compact | false | Should the checkcards be displayed with less padding around them. `true` \| `false` |
+| max | 1 | How many checkcards can be selected at once. Any positive number > 0. |
+| required | false | Whether checkcards are required in a form. `true` \| `false` |
+| selected_value | *empty string* | Comma-separated list of values selected by default, useful in edit mode. |
+| error_message | *empty string* | Message shown when selection exceeds `max`. |
+| error_heading | Error | Heading shown in the notification when displaying an error message. |
+| icon | null | Icon prefix, any icon from Heroicons. |
+| avatar | null | Avatar as an image or label. Under 4 characters renders as a label. |
+| avatar_size | medium | `tiny` \| `small` \| `medium` \| `regular` \| `big` \| `huge` \| `omg` |
+| compact | false | Display the checkcards with less padding. `true` \| `false` |
| border_color | gray | `blue` \| `red` \| `yellow` \| `green` \| `purple` \| `pink` \| `orange` \| `gray` \| `cyan` \| `violet` \| `indigo` \| `fuchsia` |
-| border_width | 2 | How thick should the border of the card be. `2` \| `4` \| `8` |
-| radius | medium | Determines the roundness of the card. `none` \| `small` \| `medium` \| `full` |
-| show_error | false | Should error messages be displayed when user has selected `max` cards. `true` \| `false` |
-| align_items | top | Determines alignment of avatar/icons. `top` \| `center` |
-| auto_select_new | true | Determines if selecting a new card unselects the last card. This ensures the user always selects `max` cards without displaying an error. `true` \| `false` |
-| class | _(blank)_ | Any additional CSS you wish to add to the checkcards container. |
-| nonce | null | Used when implementing context security policies and require to pass a nonce to inline scripts. |
+| border_width | 2 | `2` \| `4` \| `8` |
+| radius | medium | Roundness of the card. `none` \| `small` \| `medium` \| `full` |
+| show_error | false | Display an error message when the user has selected `max` cards. `true` \| `false` |
+| align_items | top | Alignment of avatar/icons. `top` \| `center` |
+| auto_select_new | true | Whether selecting a new card unselects the last one, keeping the selection count at `max`. `true` \| `false` |
+| class | *blank* | Any additional CSS for the checkcards container. |
+| nonce | null | Nonce value for content security policies applied to inline scripts. Can also be set globally via `config/bladewind.php` under the "script" key. |
### Checkcard Component
| Attribute | Default | Description |
|---|---|---|
-| class | _(blank)_ | Any additional CSS to append to the card. |
-| title | _(blank)_ | The text to display as title of the card. |
-| value | _(blank)_ | Value to pass when card is selected and form is submitted. |
-| icon | null | Display an icon prefix. You can use any icon from Heroicons. |
-| avatar | null | Display an avatar as an image or label. If this is less than 4 characters, the avatar will be displayed as a label. |
-| avatar_size | medium | Determine size of the avatar to display. `tiny` \| `small` \| `medium` \| `regular` \| `big` \| `huge` \| `omg` |
-| icon_css | _(blank)_ | Additional CSS to append to the icon. |
+| class | *blank* | Any additional CSS to append to the card. |
+| title | *blank* | Text to display as the card's title. |
+| value | *blank* | Value passed when the card is selected and the form is submitted. |
+| icon | null | Icon prefix, any icon from Heroicons. |
+| avatar | null | Avatar as an image or label. Under 4 characters renders as a label. |
+| avatar_size | medium | `tiny` \| `small` \| `medium` \| `regular` \| `big` \| `huge` \| `omg` |
+| icon_css | *blank* | Additional CSS to append to the icon. |
## Full Example
```blade
-```
-```blade
-
```
diff --git a/mcp/code-block.md b/mcp/code-block.md
new file mode 100644
index 00000000..0de887f2
--- /dev/null
+++ b/mcp/code-block.md
@@ -0,0 +1,81 @@
+---
+title: Code Block Component
+component: x-bladewind::code-block
+url: /component/code-block
+---
+
+# Code Block
+
+The code block component displays a block of source code with syntax highlighting, powered by [Prism](https://prismjs.com). It shows a small header with the language and an optional filename or title, and a copy button that puts the code on the clipboard with one click.
+
+There are two ways to give it code. Pass a `code` attribute with a PHP string, or write the snippet directly between the opening and closing tags using the default slot. The attribute is the easier and safer choice, since Blade escapes it for you automatically. Written as a slot, any `<` `>` or `&` in the code needs to be written as an HTML entity by hand, the same as any other raw `` block.
+
+```blade
+
+ Search commands
+
+
+
+
+
+
+```
+
+## Opening the Palette
+
+Command Palette renders hidden and is not tied to a trigger button by default. Open it with its keyboard shortcut (`Ctrl`+`K`, or `⌘`+`K` on macOS), or call `openCommandPalette(name)` from any element. The shortcut works even while focus sits inside another field on the page, matching the convention shared by editors, chat apps, and issue trackers.
+
+## Searching and Grouped Results
+
+As you type, Command Palette filters items by their label, description, and optional `keywords` attribute. Matching is case-insensitive and works on partial text. Groups are automatically hidden when none of their items match. A `keywords` value can match even when the words do not appear in the visible label.
+
+For server-side search, Command Palette emits `bladewind:command-palette:search` with the current query on every keystroke; listen for this event to fetch and display matching results asynchronously. While results are loading, set `loading="true"` or call `setCommandPaletteLoading(name, true)`. The built-in empty state stays hidden until loading completes.
+
+## Keyboard Behavior
+
+Focus stays in the search field the entire time the palette is open. Navigation moves a highlighted state between items instead of moving real focus, so screen readers track the current option through `aria-activedescendant` on the search field.
+
+| Key | Behavior |
+|---|---|
+| Up Arrow or Down Arrow | Move the highlight to the previous or next visible, enabled item. |
+| Home or End | Jump the highlight to the first or last visible item. |
+| Enter | Activate the highlighted item. |
+| Escape | Close the palette and restore focus to whatever opened it. |
+| Tab | Cycles between the search field and the close button while the palette is open. |
+
+## Links, Actions, and Disabled Items
+
+An item with `href` renders as a link and navigates normally. An item without `href` renders as a button, for actions handled entirely in JavaScript through the `select` event. Disabled items stay visible but cannot be highlighted or activated.
+
+## Dark Mode
+
+Command Palette follows the page dark class and keeps the backdrop, panel, highlighted item, description, and shortcut key contrast readable.
+
+## Events
+
+Before events are cancelable; call `preventDefault()` to stop the related change. All event names start with `bladewind:command-palette:`. Item events include the item name and, for links, the destination.
+
+| Event suffix | When it runs |
+|---|---|
+| `before-open`, `before-close` | Before the palette opens or closes. |
+| `opened`, `closed` | After the palette finishes opening or closing. |
+| `before-select` | Before an item is activated. Preventing this stops navigation and the close-on-select behavior. |
+| `select` | After an item is activated. |
+| `search` | On every keystroke in the search field, with the current query. |
+
+## JavaScript API
+
+Helpers return `true` on success or when the requested state already applies, and `false` for a missing target or a canceled event.
+
+```js
+openCommandPalette('app-commands');
+closeCommandPalette('app-commands');
+toggleCommandPalette('app-commands');
+resetCommandPalette('app-commands');
+setCommandPaletteLoading('app-commands', true);
+```
+
+## Using Command Palette Inside Livewire
+
+Whether the palette is open, and the current search filter, live in the palette's own DOM rather than in Livewire's component state. If a Livewire component re-renders this markup for a reason unrelated to the palette, it resets to closed. If the palette lives inside a component that can re-render for other reasons, wrap it in `wire:ignore`. The bindings that drive the palette are delegated and safe to re-run, so a re-render will not leave behind duplicate listeners.
+
+## Attributes
+
+### Command Palette Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| name | Generated | Unique public helper and DOM scope. |
+| label | Command palette | Accessible dialog and listbox name. |
+| placeholder | Search for a command… | Search field placeholder text. |
+| search-label | Same as label | Accessible name for the search field. |
+| shortcut | mod+k | Global open/close shortcut. `mod` resolves to Ctrl or Cmd. Empty disables the shortcut. |
+| size | medium | `tiny` \| `small` \| `medium` \| `big` \| `large` \| `xl` \| `omg` |
+| open | false | Initial open state. |
+| loading | false | Shows the loading row and suppresses the empty state. |
+| empty-text | No results found. | Text shown when nothing matches. |
+| loading-text | Loading… | Text shown while loading is true. |
+| close-on-select | true | Closes the palette after an item is activated. |
+| backdrop-can-close | true | Allows a backdrop click to close the palette. |
+| escape-can-close | true | Allows Escape to close the palette. |
+| close-label | Close command palette | Accessible label for the close button. |
+
+### Command Palette Group Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| name | Required | Name scoped to its Command Palette. |
+| label | Required | Visible and accessible section heading. |
+
+### Command Palette Item Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| name | Required | Event identifier for the item. |
+| label | empty | Visible and accessible label, and part of the search text. |
+| description | null | Secondary text, also matched while searching. |
+| icon | null | Heroicon name. |
+| icon-type | outline | Icon type. |
+| icon-dir | empty | Custom icon directory. |
+| shortcut | null | Display-only key combination, e.g. `Ctrl+N`. Rendered as individual `` keys. |
+| keywords | empty | Extra terms matched while searching but not displayed. |
+| href | null | Link destination. Omit for a button action handled through the `select` event. |
+| disabled | false | Removes the item from highlighting and activation. |
+| external | false | Adds external link semantics and indicator. |
+| target | null | Link target. |
+
+## Slots
+
+| Slot | Description |
+|---|---|
+| command-palette default | Command palette groups and items. |
+| command-palette footer | Content appended after the built-in keyboard hints in the footer. |
+| group default | Items belonging to the group. |
+| item default | Custom item copy while Command Palette keeps the option and search semantics. |
+
+## Full Example
+
+```blade
+
+
+
+ Signed in as Ama Mensah
+
+```
diff --git a/mcp/context-menu.md b/mcp/context-menu.md
new file mode 100644
index 00000000..1773b4f3
--- /dev/null
+++ b/mcp/context-menu.md
@@ -0,0 +1,92 @@
+---
+title: Context Menu Component
+component: x-bladewind::context-menu
+url: /component/context-menu
+---
+
+# Context Menu
+
+`x-bladewind::context-menu` gives any region a right-click action menu — a table row, a card, a canvas element,
+anything. It follows the same visual language as Dropmenu, but opens at the pointer instead of anchored to a trigger,
+and adds nested submenus, disabled items, and separators. Placement is always viewport-aware: the menu (and any
+submenu) flips away from whichever edge it would otherwise overflow.
+
+## Basic Usage
+
+```blade
+
+
+ Right-click anywhere in this box
+
+
+ Edit
+ Duplicate
+ Delete
+
+```
+
+The `region` slot is the area that responds to a right-click (or the keyboard context-menu key — both dispatch the
+same browser `contextmenu` event, so no separate keyboard wiring is needed to trigger it). Every other child is a
+menu item, in the order they should appear.
+
+## Disabled items
+
+Set `disabled="true"` on an item to grey it out and remove it from pointer and keyboard interaction entirely — it is
+skipped by arrow-key navigation and cannot be clicked or activated.
+
+```blade
+Restricted action
+```
+
+## Tone
+
+`tone="danger"` tints an item's label and icon red, for destructive actions. The default is `normal`.
+
+## Nested submenus
+
+Give an item a `submenu` slot containing further `x-bladewind::context-menu.item` elements to turn it into a submenu
+trigger. A submenu opens on hover, click, or the right arrow key, and can itself contain another submenu — nesting is
+unlimited. The left arrow key or Escape closes the deepest open submenu and returns focus to its parent item.
+
+```blade
+
+ New
+
+ File
+ Folder
+
+
+```
+
+## Keyboard support
+
+| Key | Action |
+|---|---|
+| Down / Up | Move focus to the next or previous enabled item. |
+| Right | Open the focused item's submenu, if it has one. |
+| Left | Close the current submenu and refocus its parent item. |
+| Enter / Space | Activate the focused item, or open its submenu. |
+| Home / End | Jump to the first or last enabled item. |
+| Escape | Close the current submenu, or the whole menu if none is open. |
+
+## Attributes
+
+### Context Menu
+
+| Attribute | Default | Description |
+|---|---|---|
+| name | _(auto-generated)_ | Uniquely identifies this instance in the DOM and its JavaScript. |
+| disableNative | true | false lets the browser's own context menu show and disables this component entirely. |
+| padded | true | Padding inside the menu list. |
+| class | _(blank)_ | Additional CSS classes for the menu list. |
+
+### Context Menu Item
+
+| Attribute | Default | Description |
+|---|---|---|
+| icon | _(blank)_ | Any Heroicons name. |
+| disabled | false | Greys the item out and removes it from pointer and keyboard interaction. |
+| tone | normal | `normal` \| `danger` |
+| divider | false | Renders a separator line instead of an item; ignores every other prop. |
+| submenu | _(none)_ | A named slot of further items, turning this item into a submenu trigger. |
diff --git a/mcp/copy-button.md b/mcp/copy-button.md
new file mode 100644
index 00000000..b14b5c2b
--- /dev/null
+++ b/mcp/copy-button.md
@@ -0,0 +1,51 @@
+---
+title: Copy Button Component
+component: x-bladewind::copy-button
+url: /component/copy-button
+---
+
+# Copy Button
+
+`x-bladewind::copy-button` copies a value — or its own wrapped content — to the clipboard on click, briefly swapping
+its icon to a checkmark and announcing success or failure to assistive technology.
+
+## Basic Usage
+
+```blade
+npm install bladewindui
+```
+
+With no `value`, the button copies its own slot's trimmed text — the display and the copied value never drift apart
+because there is only one string to keep in sync.
+
+## Icon-only, with an explicit value
+
+Pass `value` directly for an icon-only trigger next to something that isn't itself plain copyable text — a masked
+API key, a formatted table cell, and so on.
+
+```blade
+sk_live_••••••••1234
+
+
+```
+
+## Forcing A Network
+
+Leave `brand` unset to auto-detect from the number. Set it explicitly to override, for example a saved card where the network is already known but the full number is not shown.
+
+```blade
+
+
+
+
+```
+
+## Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| name | auto-generated | Used as the JS variable the component is exposed on (`window.{name}`) and to scope its script tags. Not a form field — this component does not submit. |
+| cardholder_name | _blank_ | Name printed on the card. |
+| number | _blank_ | Card number, auto-grouped per network as the user types. A masked value like `•••• •••• •••• 4242` is preserved as-is. |
+| expiry_month / expiry_year | _blank_ | Two-digit month (`01`-`12`) and year. |
+| cvc | _blank_ | Security code (3 digits, 4 for American Express). |
+| brand | auto-detected | `visa` \| `mastercard` \| `amex` \| `discover` \| `diners` \| `jcb` \| `unionpay` \| `maestro` |
+| color | primary | Gradient colour, from the shared palette. Ignored in the outline variant. |
+| variant | gradient | `gradient` for the full-colour face, `outline` for a bare silhouette, or `inline` for number/expiry/CVC fields only. |
+| flipped | false | Shows the back face. `true` \| `false` |
+| disabled | false | Disables every field and hides the flip button. `true` \| `false` |
+| readonly | false | Makes every field read-only. `true` \| `false` |
+| required | false | Whether `validate()` fails while any field is incomplete. `true` \| `false` |
+| error_message | _blank_ | Message shown when validation fails and `show_error_inline` is set. |
+| show_error_inline | false | Renders the error message beneath the card. `true` \| `false` |
+| on_change | _blank_ | Name of a JavaScript function called with the structured value whenever it changes. |
+| class | _blank_ | Additional CSS classes for the wrapper element. |
diff --git a/mcp/currency-input.md b/mcp/currency-input.md
new file mode 100644
index 00000000..66df37a6
--- /dev/null
+++ b/mcp/currency-input.md
@@ -0,0 +1,61 @@
+---
+title: Currency Input Component
+component: x-bladewind::currency-input
+url: /component/currency-input
+---
+
+# Currency Input
+
+`x-bladewind::currency-input` wraps Input's existing money-masking (thousands separators, a fixed decimal precision)
+and adds the one thing that mask alone cannot: the correct currency symbol, in the correct position, with separators
+written the way the given locale actually writes them.
+
+## Basic Usage
+
+```blade
+`, so every interaction (sorting, selecting, paging, searching) happens through real, independently keyboard-operable controls rather than a hand-rolled widget.
+
+## Basic Usage
+
+```blade
+'
+ .ucfirst($value).' ';
+ },
+ ],
+];
+```
+
+Because `format` output is not escaped, never feed it raw user input without sanitising first. Build the HTML around a trusted value, or run untrusted text through `e()` before it goes into the string.
+
+### Custom Sort Values
+
+Sorting compares the raw cell value by default, before `format` runs. That breaks down for a column whose sortable order should not match the raw or formatted value, e.g. a status that should sort by severity rather than alphabetically. Give the column its own `sort($value, $row)` callback to override the comparison value:
+
+```blade
+
+
+ Export
+ Delete
+
+
+```
+
+## Pagination and Server-Driven State
+
+Set `paginated="true"` with `page-size` for client-side pagination. The grid renders its own previous and next footer and keeps it in sync with sorting and searching.
+
+Client pagination still ships every row to the browser and pages through them there, fine for a few hundred rows but the wrong tool once a dataset grows past what is reasonable to send on every page load.
+
+Pass a real Laravel paginator through `paginator` instead of setting `paginated` directly; the grid detects it and switches into server mode automatically, rendering standard page links. `rows` should be the paginator's current-page items, not the full dataset:
+
+```php
+// in your controller or route closure
+$staff = Staff::query()->orderBy('company_name')->paginate(8);
+return view('staff.index', ['staff' => $staff]);
+```
+
+```blade
+
+
+ Export CSV
+
+
+```
+
+## Custom Layout
+
+Skip `columns` and `rows` entirely for a fully custom layout: a `header` slot for `` content, and the default slot for hand-written ` ` rows. This is the escape hatch for a table body that does not fit the column model at all, e.g. merged cells or a summary row. A custom layout opts out of the grid's own sorting, searching, and pagination automation, since those work against the `columns` and `rows` the grid normalises internally; you are responsible for reimplementing any of that behaviour against your hand-written markup.
+
+```blade
+
+
+ Reference
+ Customer
+ Total
+
+
+
+ ORD-1041
+ Kofi Addo
+ $84.00
+
+
+ Total
+ $84.00
+
+
+```
+
+## Events
+
+Before events are cancelable. Call `preventDefault()` on the event to stop the related change, useful for confirming a destructive selection change or blocking a sort while a save is in flight. All event names start with `bladewind:data-grid:`.
+
+| Event suffix | When it runs |
+|---|---|
+| `before-sort-change`, `sort-change` | Before and after a column's sort state changes. |
+| `before-select-change`, `select-change` | Before and after row selection changes. Preventing the before event reverts the checkbox or radio. |
+| `before-page-change`, `page-change` | Before and after the current client page changes. |
+| `search` | On every keystroke in the search field, with the current query. |
+
+```js
+document.addEventListener('bladewind:data-grid:before-select-change', (event) => {
+ if (event.detail.name !== 'orders-grid') return;
+ if (event.detail.selecting && event.detail.row.status === 'refunded') {
+ if (!confirm('This order was refunded. Select it anyway?')) {
+ event.preventDefault();
+ }
+ }
+});
+```
+
+## JavaScript API
+
+Every helper returns `true` when it completes, or when the requested state already applies, and `false` when the target is missing or a cancelable event was prevented.
+
+| Function | What it does |
+|---|---|
+| `sortDataGrid(name, key, direction)` | Sorts a client-mode grid by the given column, direction is `'asc'`, `'desc'`, or `null` to clear. |
+| `setDataGridPage(name, page)` | Jumps to a page in a client-paginated grid. |
+| `selectAllDataGridRows(name, selected)` | Selects or deselects every visible row, matching the header checkbox. |
+| `clearDataGridSelection(name)` | Clears the current selection entirely. |
+| `dataGridSelectedKeys(name)` | Returns an array of the currently selected row keys. |
+| `setDataGridLoading(name, loading)` | Toggles the dimmed, busy loading state. |
+| `resetDataGrid(name)` | Clears search, sort, selection, and returns to page one, all at once. |
+
+```js
+sortDataGrid('orders-grid', 'total', 'desc');
+setDataGridPage('orders-grid', 2);
+selectAllDataGridRows('orders-grid', true);
+dataGridSelectedKeys('orders-grid'); // ['3', '7', '12']
+clearDataGridSelection('orders-grid');
+setDataGridLoading('orders-grid', true);
+resetDataGrid('orders-grid');
+```
+
+## Using Data Grid Inside Livewire
+
+Client-side sorting, searching, pagination, and row selection all live in the grid's own DOM, in attributes and checkbox state, rather than in Livewire's component state, so those interactions work fine on their own inside a Livewire component. What can catch you out is an unrelated re-render, one that happens for a reason that has nothing to do with the grid: because that state is not mirrored back to Livewire, such a re-render can reset the current page, sort order, or selection. If the grid lives inside a component that re-renders for other reasons, wrap it in `wire:ignore`. Alternatively, set `client-sort="false"` and `client-search="false"` and drive the grid from Livewire using the `before-*` and `*-change` events described above.
+
+## Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| name | Generated | Unique public helper and DOM scope. |
+| label | Data grid | Accessible table name. |
+| columns | [] | Column model. Omit with rows for a custom layout. |
+| rows | null | Array of associative arrays or objects to render. |
+| row-key | id | Field used as each row's unique identity. |
+| selectable | false | Adds a selection column. |
+| selection-mode | multiple | `multiple` (checkboxes) or `single` (radios). |
+| selected | [] | Row keys to preselect. |
+| sortable | false | Makes every column sortable. A column's own sortable key wins per column. |
+| sort-key | null | Column key to render as initially sorted. |
+| sort-direction | null | `asc` or `desc`, paired with sort-key. |
+| client-sort | true | Reorders rows in the browser. When false, only the indicator updates and the app must reorder the data. |
+| searchable | false | Renders the toolbar search field. |
+| search-placeholder | Search… | Search field placeholder text. |
+| client-search | true | Filters rows in the browser. When false, only the search event fires. |
+| paginated | false | Enables client pagination. Implied automatically by passing paginator. |
+| page-size | 25 | Rows per page in client pagination mode. |
+| paginator | null | A Laravel paginator, for server-driven pagination. |
+| sticky | true | Pins the header while the body scrolls. |
+| loading | false | Dims the table and shows a progress indicator. |
+| empty-text | No records found. | Text shown when there are no rows. |
+| striped | false | Alternating row background. |
+| bordered | false | Vertical cell borders. |
+| dense | false | Reduced cell padding. |
+| height | null | Max height for the scrollable body, e.g. `24rem`. |
+| select-all-label | Select all rows | Accessible label for the header checkbox. |
+| clear-selection-label | Clear selection | Label for the clear-selection control. |
+
+## Slots
+
+| Slot | Description |
+|---|---|
+| toolbar | Content appended after the search field. |
+| bulk-actions | Custom buttons in the selection bar. |
+| header | Custom `` content, used instead of columns. |
+| default | Custom ` ` rows, used instead of rows. |
+
+## Full Example
+
+```blade
+
+
+ Export CSV
+
+
+ Delete selected
+
+
+```
diff --git a/mcp/datepicker.md b/mcp/datepicker.md
index 235fbd99..56bed19c 100644
--- a/mcp/datepicker.md
+++ b/mcp/datepicker.md
@@ -6,107 +6,124 @@ url: /component/datepicker
# Datepicker
-Display a datepicker so user can select a date. The datepicker component is locale friendly. Months and days of the week are translated.
+Display a datepicker so users can select a date. It is locale friendly: months and days of the week are translated.
## Basic Usage
```blade
-
-
```
## Range Calendar
-The range datepicker allows you to select a range of dates by setting `range="true"`. In the input field, the range of dates selected are separated with a dash (-). For example, a selected date range will be displayed in the input as **2025-01-10 - 2025-01-31**.
+Set `range="true"` to select a range of dates. In the input field, the two dates are separated with a dash, e.g. `2025-01-10 - 2025-01-31`.
```blade
-`, stacked on mobile and laid out label-beside-value from the `sm` breakpoint up.
+
+```blade
+
+ Jane Cooper
+ jane.cooper@example.com
+ Admin
+
+```
+
+## Action Slots
+
+Give an item an `action` slot for a control shown beside its value, such as an edit link or a copy button.
+
+```blade
+
+ jane.cooper@example.com
+
+ Edit
+
+
+```
+
+## Striped Rows
+
+Set `striped` on the list to alternate a subtle background on every row. It propagates from the list to each item automatically.
+
+```blade
+
+ Pro
+ March 4, 2027
+ 12 of 20 used
+
+```
+
+## Attributes
+
+### Description List Component
+
+| Attribute | Default | Description |
+|---|---|---|
+| divided | true | Determines if a horizontal rule is shown between rows. `true` \| `false` |
+| striped | false | Alternates a subtle background on every row. Propagates to items automatically. `true` \| `false` |
+| class | _blank_ | Any additional CSS you wish to add to the wrapper element. |
+
+### Description List Item Component
+
+| Attribute | Default | Description |
+|---|---|---|
+| label | _blank_ | The row's label. |
+| action | _none_ | A named slot rendered beside the value. |
+| class | _blank_ | Any additional CSS you wish to add to the row. |
diff --git a/mcp/divider.md b/mcp/divider.md
new file mode 100644
index 00000000..21394d7b
--- /dev/null
+++ b/mcp/divider.md
@@ -0,0 +1,76 @@
+---
+title: Divider Component
+component: x-bladewind::divider
+url: /component/divider
+---
+
+# Divider
+
+A horizontal or vertical rule for separating layout regions — sections of a form, rows in a list, or items in a
+toolbar. It ranges from a plain line to a line split by a centered label, and can be purely decorative or a real
+`role="separator"` a screen reader announces.
+
+## Basic Usage
+
+```blade
+
+ Edit
+ Duplicate
+
+```
+
+## Spacing
+
+`spacing` controls the margin either side of the line: `none`, `small`, `medium` (default), or `large`.
+
+```blade
+Open drawer
+
+
+
+
+
+
+
+
+
+
+
Victoria Ferguson
+
victoria@ferguson.eu
+
+
+
+```
+
+## Positions
+
+Use `left`, `right`, `top`, or `bottom`. These are physical viewport edges, so left and right remain predictable in RTL pages.
+
+```blade
+...
+...
+...
+...
+```
+
+## Sizes
+
+Sizes are adapted to the drawer direction: left and right drawers change width, top and bottom drawers change height. Available values are `tiny`, `small`, `medium`, `big`, `large`, `xl`, and `omg`.
+
+```blade
+...
+```
+
+## Modal and Non-modal Behaviour
+
+A drawer is modal by default: it has a backdrop, traps focus, and prevents background scrolling. Set `modal="false"` for supporting content that should leave the page interactive.
+
+```blade
+...
+```
+
+## Header and Footer Slots
+
+Use the named header and footer slots to customize those regions while keeping the drawer layout and scrolling behavior.
+
+```blade
+
+ Custom header
+ Form content
+ Custom footer
+
+```
+
+## Icons and Close Controls
+
+Set `icon`, `icon-type`, and `icon-dir` using the Icon component contract. Set `show-close-button="false"` when another clear close action is present.
+
+```blade
+...
+```
+
+## Backdrop and Escape Options
+
+Backdrop clicks and the Escape key close a modal drawer by default. Disable either behavior for a workflow that requires an explicit decision, and always provide a visible close action.
+
+```blade
+
+ ...
+
+ Cancel
+
+
+```
+
+## Programmatic Show, Hide, and Toggle
+
+The three public helpers accept the drawer name and return `false` when no matching state change can be made.
+
+```js
+showDrawer('customer-details');
+hideDrawer('customer-details');
+toggleDrawer('customer-details');
+```
+
+The drawer also emits `bladewind:drawer-opened` and `bladewind:drawer-closed` events. Each event bubbles and includes the drawer name in `event.detail.name`.
+
+## Long and Scrollable Content
+
+The body region scrolls independently while the header and footer remain visible.
+
+## Responsive, Dark Mode, and RTL
+
+On narrow screens, side drawers never exceed the viewport width. The component uses the active dark theme automatically and respects reduced motion preferences. Left and right refer to physical edges in both LTR and RTL documents.
+
+## Accessibility and Focus Management
+
+Modal drawers render with dialog semantics and `aria-modal="true"`. The title labels the drawer and the description is connected with `aria-describedby`. If there is no title, provide `aria-label` or `aria-labelledby`.
+
+Opening moves focus to the first focusable control, or to the panel when there are no controls. Modal focus stays inside the active drawer. Closing restores focus to the control that opened it. When drawers are stacked, Escape affects only the top drawer.
+
+## Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| name | generated | Unique drawer name used by the JavaScript helpers. |
+| title | _(blank)_ | Visible title and accessible name. |
+| description | _(blank)_ | Supporting text connected to the drawer description. |
+| position | right | Physical edge: `left`, `right`, `top`, or `bottom`. |
+| size | medium | `tiny` \| `small` \| `medium` \| `big` \| `large` \| `xl` \| `omg` |
+| modal | true | Enable backdrop, focus trap, and scroll locking. |
+| open | false | Render the drawer open initially. |
+| show-close-button | true | Show the header close control. |
+| close-label | Close drawer | Accessible label for the close control. |
+| backdrop-can-close | true | Allow backdrop clicks to close a modal drawer. |
+| escape-can-close | true | Allow Escape to close the active drawer. |
+| icon | _(blank)_ | Header icon name. |
+| icon-type | outline | Icon type passed to the Icon component. |
+| icon-dir | _(blank)_ | Custom icon directory passed to the Icon component. |
+
+## Slots
+
+| Slot | Description |
+|---|---|
+| default | Drawer body content. |
+| body | Named alternative to the default body slot. |
+| header | Custom header content. The configured close button remains available. |
+| footer | Footer actions or supporting content. |
+
+## JavaScript API
+
+| Function or event | Description |
+|---|---|
+| `showDrawer(name)` | Open a drawer, record the trigger, move focus, and lock scroll when modal. |
+| `hideDrawer(name)` | Close a drawer and restore focus. |
+| `toggleDrawer(name)` | Open or close a drawer based on its current state. |
+| `bladewind:drawer-opened` | Bubbling event emitted after opening. |
+| `bladewind:drawer-closed` | Bubbling event emitted after closing. |
+
+## Using Drawer Inside Livewire
+
+Whether the drawer is open or closed lives in the drawer's own DOM rather than in Livewire's component state. If a Livewire component re-renders this markup for a reason that has nothing to do with the drawer, it silently closes. This matters most for a drawer that can stay open for a while, such as a filter panel or a form, inside a component that can also re-render for other reasons. In that situation, wrap the drawer in `wire:ignore` so Livewire leaves it alone.
+
+## Full Example
+
+```blade
+
+ Customer profile content
+
+```
diff --git a/mcp/dropmenu.md b/mcp/dropmenu.md
index 4296dc9f..60f61f07 100644
--- a/mcp/dropmenu.md
+++ b/mcp/dropmenu.md
@@ -6,7 +6,9 @@ url: /component/dropmenu
# Dropmenu
-Useful for displaying menu items in a dropdown. This is very different from the [Select component](/component/select). The Select component can pass values as a form element. The Dropmenu does not pass values around and is mostly useful for accessing quick actions.
+Displays menu items in a dropdown for quick actions. Unlike the Select component, the Dropmenu does not pass values around as a form element.
+
+## Basic Usage
```blade
@@ -16,7 +18,7 @@ Useful for displaying menu items in a dropdown. This is very different from the
```
-By default the Dropmenu is triggered using the `horizontal ellipsis` icon found on [Heroicons](https://heroicons.com/). You can trigger the menu using any other icon from Heroicons or using any other element. To use an icon as the trigger, the trick is to append the word **-icon** to the end of the name of the icon defined on Heroicons.
+By default the Dropmenu is triggered by the horizontal ellipsis icon from Heroicons. To trigger it with any other Heroicon, append `-icon` to the icon's name and set it as `trigger`.
```blade
@@ -39,11 +41,10 @@ By default the Dropmenu is triggered using the `horizontal ellipsis` icon found
### trigger_css
-It is also possible to modify the trigger css. This css applies to any item you specify as the trigger but most useful if you specify an icon as the trigger. This is achieved by defining TailwindCSS classes for the `trigger_css` attribute.
+Apply TailwindCSS classes to the trigger element, most useful when the trigger is an icon.
```blade
-
+
Add to playlist
Play again
@@ -51,20 +52,18 @@ It is also possible to modify the trigger css. This css applies to any item you
### trigger_on
-By default the Dropmenu is displayed when you click on the trigger. It is possible to change this behaviour by defining the `trigger_on` attribute. There are only two available options: `click` and `mouseover`.
+By default the menu opens on click. Set `trigger_on="mouseover"` to open on hover instead. Available values: `click`, `mouseover`.
```blade
-
+
Add to playlist
Play again
```
-### Non Icon Triggers
+### Non-Icon Triggers
-To trigger the Dropmenu using any HTML element other than an icon, you will need to define the trigger as a slot.
+Define the trigger as a slot to use any HTML element instead of an icon.
```blade
@@ -97,13 +96,10 @@ To trigger the Dropmenu using any HTML element other than an icon, you will need
## Dropmenu Item Actions
-The Dropmenu items are the actual line items within your Dropmenu. Each item can contain any piece of HTML code so you completely have control over what action is assigned to each menu item. BladewindUI does not interfere. For convenience, you can specify an `onclick` attribute.
-
-Dropmenu Items can contain HTML so their content is all up to you.
+Each dropmenu item can contain any HTML, giving you full control over its action. Use the `onclick` attribute for convenience.
```blade
-
+
Go to Library
@@ -117,7 +113,7 @@ Dropmenu Items can contain HTML so their content is all up to you.
### Headers
-It is possible to define a header for your Dropmenu component. There can be several headers in a Dropmenu. The header is still a `x-bladewind::dropmenu.item` component so can contain any HTML. The only difference between this and other items is there is no hover effect, the cursor displayed is the default pointer and there is a divider separating the header from the next menu item. To define a Dropmenu item as a header, set `header="true"`.
+Set `header="true"` on a `dropmenu.item` to render it as a header — no hover effect, default pointer cursor, and a divider separating it from the next item. Multiple headers are allowed.
```blade
@@ -127,7 +123,7 @@ It is possible to define a header for your Dropmenu component. There can be seve
### Icons
-Even though it is possible to define your own icon as part of the Dropmenu item's content, there is a shortcut that allows you to define any of the icons available on [Heroicons](https://heroicons.com). This makes use of the BladewindUI [Icon component](/component/icon). This is useful only if you have menu items that fit on one line and you want to prefix each line with an icon. To define a Dropmenu item with an icon, set the `icon` attribute with any icon name from Heroicons. Unlike the icon used in the `trigger` attribute of the Dropmenu component, items do not require the **-icon** at the end of the icon name.
+Set `icon` on a `dropmenu.item` to prefix it with a Heroicon (via the Icon component), without the `-icon` suffix needed by the trigger.
```blade
@@ -135,25 +131,23 @@ Even though it is possible to define your own icon as part of the Dropmenu item'
```
-By default, icons are positioned on the left of the menu item content. To switch the icon position to the right of the menu item content, set `icon_right="true"`. Setting the attribute on the `x-bladewind::dropmenu` component will shift all menu items in the menu to the right. Alternatively, you can set the attribute on one or more menu items within the Dropmenu component.
+Icons are positioned on the left by default. Set `icon_right="true"` on the Dropmenu component to shift all item icons to the right, or on individual items to shift just those.
```blade
-
- ...
-
+ ...
```
### Dividers
-You may want to logically divide your Dropmenu into sections. You can either do that with headers or dividers. A divider is simply a non-clickable line separating menu items. To define a Dropmenu item as a divider, set `divider="true"`. Any text added to the menu item will be ignored.
+Set `divider="true"` on an item to render a non-clickable divider line (any text content is ignored).
```blade
@@ -161,31 +155,88 @@ By default Dropmenu Items are not divided. You can tell each menu item apart on
```
+### Full Example: Headers, Icons and Dividers
+
+```blade
+
+
+
+
+
+
+
+
Jane A. Doe
+
@jane-the-coder
+
jane@bladewindui.com
+
+
+
+ Edit Profile
+
+
+ Delete Profile
+
+
+ Your Repositories
+ Your Projects
+ Your Organizations
+ Your Stars
+
+
+ Sign Out
+
+
+```
+
## Menu Position
-The Dropmenu component for now supports two menu positions: left and right. This is achieved by setting the `position` attribute on the Dropmenu component. The default position is `right` so you can ignore this attribute if you intend to use the component as is.
+Set `position` to `left` or `right` (default `right`) to control where menu items appear relative to the trigger.
```blade
-...
-
-
-
-...
+ ...
```
## Scrollable Menu Items
-You could have a long list of menu items in your Dropmenu. If you don't want all items showing, you can set `scrollable="true"` on the Dropmenu component. This will reduce the menu items container to a default height of `200px` and scroll every menu item outside this view area. If the default height does not meet your needs, you can define your own height by setting the `height` attribute. This takes any positive integer without the "px".
+Set `scrollable="true"` to cap the menu items container at a default height of `200px` and scroll the rest. Override the height with the `height` attribute (a positive integer, no "px").
```blade
-
-...
+
+ ...
```
-If you have multiple Dropmenus on your page and experience issues with only the first Dropmenu showing and subsequent ones not showing, set `modular="true"` on the very first Dropmenu component on your page.
+If you have multiple Dropmenus on one page and only the first shows, set `modular="true"` on the first Dropmenu component on the page.
+
+## JavaScript API
+
+Each dropmenu creates a `BladewindDropmenu` instance assigned to a variable named after its `name` attribute, callable from your own scripts or inline handlers. If you set `name` yourself, use only letters, numbers, and underscores (hyphens are invalid in JS identifiers) — the auto-generated default already follows this rule.
+
+| Method | Description |
+|---|---|
+| `name.show()` | Open the menu and position it against its trigger. |
+| `name.hide()` | Close the menu. |
+| `name.toggle()` | Open or close the menu based on its current state. |
+
+```js
+profile_menu.show();
+profile_menu.hide();
+profile_menu.toggle();
+```
## Attributes
@@ -193,34 +244,39 @@ If you have multiple Dropmenus on your page and experience issues with only the
| Attribute | Default | Description |
|---|---|---|
-| `name` | `uniqid('bw-dropmenu-')` | Optional unique name for the component. Usually useful if you wish to target a menu from CSS to define overwriting styles. |
-| `trigger` | `ellipsis-horizontal-icon` | The element to trigger the menu. Usually what a user will click on to show the menu. |
-| `trigger_css` | blank | Additional css to apply to the trigger. |
-| `trigger_on` | `click` | Which event should trigger the menu. `click` `mouseover` |
-| `divided` | `false` | Should menu items have lines dividing them. `true` `false` |
-| `scrollable` | `false` | Should menu items scroll after 200px. `true` `false` |
-| `height` | `200` | Default height for menu items container. When `scrollable=true`, menu items container will be restricted to this height. Accepts a positive integer. |
-| `hide_after_click` | `true` | Should the menu be hidden after clicking on any of the menu items. `true` `false` |
-| `icon_right` | `false` | Align the icon to the right of the menu item. Applies to all items in the menu. `true` `false` |
-| `class` | blank | Additional css for the menu items container. |
-| `position` | `right` | How should the menu items be positioned relative to the trigger. `right` `left` |
-| `padded` | `false` | Should the container for the menu items be padded. `true` `false` |
-| `modular` | `false` | Determines if script tags used within the component should have `type="module"`. Useful sometimes when working with Vite js. `true` `false` |
-| `nonce` | `null` | Used when implementing context security policies and require to pass a nonce to inline scripts. For convenience, you can set your `nonce` value in the `config/bladewind.php` file under the "script" key. |
+| name | uniqid('bw-dropmenu-') | Optional unique name, useful to target a menu from CSS. |
+| trigger | ellipsis-horizontal-icon | The element that triggers the menu. |
+| trigger_css | *blank* | Additional CSS applied to the trigger. |
+| trigger_on | click | Event that triggers the menu. `click` \| `mouseover` |
+| divided | false | Divide menu items with lines. `true` \| `false` |
+| scrollable | false | Scroll menu items after 200px. `true` \| `false` |
+| height | 200 | Height for the menu items container when `scrollable=true`. Positive integer. |
+| hide_after_click | true | Hide the menu after clicking a menu item. `true` \| `false` |
+| icon_right | false | Align icons to the right of every menu item. `true` \| `false` |
+| class | *blank* | Additional CSS for the menu items container. |
+| position | right | Position of menu items relative to the trigger. `right` \| `left` |
+| padded | false | Pad the menu items container. `true` \| `false` |
+| modular | false | Whether script tags in the component use `type="module"`. Useful with Vite. `true` \| `false` |
+| nonce | null | Nonce value for content security policies applied to inline scripts. Can also be set globally via `config/bladewind.php` under the "script" key. |
+| trigger_label | *blank* | Accessible name for the trigger, exposed as `aria-label`. Worth setting when the trigger is icon-only, since it otherwise reaches a screen reader unnamed. |
### Dropmenu Item Component Attributes
| Attribute | Default | Description |
|---|---|---|
-| `icon` | blank | Any Heroicon icon to display as prefix to the menu item. |
-| `dir` | blank | Directory to load the icon from. See the [Icon](/component/icon#custom-dir) component for usage. |
-| `icon_css` | blank | Additional css to apply to the icon. |
-| `icon_right` | `false` | Align the icon to the right of the menu item. Applies to the menu item the attribute is declared on. `true` `false` |
-| `divider` | `false` | Is this menu item a divider. `true` `false` |
-| `header` | `false` | Is this menu item a header. `true` `false` |
-| `hover` | `true` | Should this menu item change its background colour on mouseover. `true` `false` |
-| `padded` | `false` | Should the menu item be padded. `true` `false` |
-| `class` | blank | Additional css to add to the menu item. |
+| icon | *blank* | Any Heroicon icon to prefix the menu item. |
+| dir | *blank* | Directory to load the icon from. See the Icon component. |
+| icon_css | *blank* | Additional CSS applied to the icon. |
+| icon_right | false | Align the icon to the right, for this item only. `true` \| `false` |
+| divider | false | Render this item as a divider. `true` \| `false` |
+| header | false | Render this item as a header. `true` \| `false` |
+| hover | true | Change background colour on mouseover. `true` \| `false` |
+| padded | false | Pad the menu item. `true` \| `false` |
+| class | *blank* | Additional CSS for the menu item. |
+
+## Using Dropmenu Inside Livewire
+
+The menu tracks its open/closed state outside of the DOM that Livewire manages, so an unrelated re-render resets it to closed — wrap the trigger and menu in `wire:ignore` if this happens. The component also guards against a Livewire re-render creating a second copy of itself, so re-rendering won't leave behind duplicate click listeners.
## Full Example
@@ -246,8 +302,7 @@ If you have multiple Dropmenus on your page and experience issues with only the
header="false"
hover="false"
class="p-2">
- ...
+ ...
-
```
diff --git a/mcp/empty-state.md b/mcp/empty-state.md
index cfbf75c6..805d086c 100644
--- a/mcp/empty-state.md
+++ b/mcp/empty-state.md
@@ -6,9 +6,7 @@ url: /component/empty-state
# Empty State
-Display this when there is nothing to display. This prevents your users from seeing boring blank pages. The empty state component is intentionally minimal, bearing in mind that different applications have different empty state requirements.
-
-A default SVG image is bundled with BladewindUI at `public/vendor/bladewind/images/empty-state.svg` and used when no `image` attribute is specified.
+Display this when there is nothing to display, instead of a blank page. The component is kept minimal since every application has its own specific empty state requirements.
## Basic Usage
@@ -20,52 +18,59 @@ A default SVG image is bundled with BladewindUI at `public/vendor/bladewind/imag
```
-## Custom Image
+This uses the default bundled empty state image, available at `public/vendor/bladewind/images/empty-state.svg`.
+
+## Custom Images
+
+Set the `image` attribute to use your own image. BladewindUI looks for the file relative to the `public` directory.
```blade
-
+ onclick="alert('you clicked me')">
```
-## With a Heading
+## Headings
+
+Set `heading` to let the user know immediately what's happening, without reading the full message.
```blade
```
-## Custom Content (No Image)
+## Custom Content
-Set `show_image="false"` to take full control of the empty state content via the default slot.
+Ignore the attributes entirely and put your own content inside the component. Set `show_image="false"` to suppress the default image.
```blade
- ...
- You have no biometric data available
+
+
+ You have no biometric data available
Add biometric info
```
-## Without a Call to Action
+## No Call to Action
-Omit `button_label` (or set it to an empty string) to display an empty state with no action button.
+Leave out `button_label` (or set it to an empty string) for an empty state with no action, such as a "Recent Activities" section.
```blade
+ message="Your recent activities list will take shape as
```
@@ -74,16 +79,16 @@ Omit `button_label` (or set it to an empty string) to display an empty state wit
| Attribute | Default | Description |
|---|---|---|
-| image | /vendor/bladewind/images/empty-state.svg | Image to display |
-| show_image | true | Show or hide the image. Set to `false` to control all content via slot. `true` \| `false` |
+| image | /vendor/bladewind/images/empty-state.svg | Image to display. |
+| show_image | true | Whether the image should be displayed. Set `false` to control the entire content yourself. `true` \| `false` |
| image_size | medium | Size of the image. `small` \| `medium` \| `large` \| `xl` \| `omg` |
-| for_select | false | Set to `true` when used inside a Select component. `true` \| `false` |
-| heading | _(blank)_ | Optional heading displayed above the message |
-| message | _(blank)_ | Main message text |
-| button_label | _(blank)_ | Text for the call to action button. Omit to hide the button |
-| onclick | _(blank)_ | JavaScript to execute when the button is clicked |
-| image_css | _(blank)_ | Additional TailwindCSS classes for the image |
-| class | bw-empty-state | Additional CSS classes for the wrapper |
+| for_select | false | Whether this empty state is used by a select component. When `true`, it's hidden and only shown by the select component referencing its `name`. `true` \| `false` |
+| button_label | *blank* | Text on the call to action button. |
+| onclick | *blank* | Action to run when the button is clicked, e.g. `onclick="location.href='/dashboard'"` or a JS helper call. |
+| heading | *blank* | Empty state heading. |
+| message | *blank* | Empty state message. |
+| class | bw-empty-state | Any additional CSS classes. |
+| image_css | *blank* | Any additional CSS classes applied to the image. |
## Full Example
diff --git a/mcp/file-preview.md b/mcp/file-preview.md
new file mode 100644
index 00000000..2577af70
--- /dev/null
+++ b/mcp/file-preview.md
@@ -0,0 +1,55 @@
+---
+title: File Preview Component
+component: x-bladewind::file-preview
+url: /component/file-preview
+---
+
+# File Preview
+
+`x-bladewind::file-preview` is the read-only display counterpart to Filepicker — a compact row showing a thumbnail
+or file-type icon, the filename, its size, and download/remove actions. Use it for a list of already-uploaded files:
+attachments on a record, documents in a table row, files a Filepicker has already accepted.
+
+## Basic Usage
+
+```blade
+` with class `placeholder-[$name] hidden` (replacing `[$name]` with the filepicker's name) before the filepicker component.
```blade
-
-
+
+
+
+
Drag & Drop Invoices
-
PDFs only. Max of 10mb
+
+ PDFs only. Max of 10mb
+
```
-## Drag-and-Drop or Browse Only
+## Allow Drag and Drop Only
+
+Set `can_browse="false"` to disable file browsing and only allow drag & drop.
+
+```blade
+
+```
+
+## Allow Browsing of Files Only
+
+Set `can_drop="false"` to disable drag & drop and only allow browsing.
```blade
-{{-- drag and drop only --}}
-
+
+```
+
+## Disable the Filepicker
-{{-- browse only --}}
-
+```blade
+
```
-## File Size Limits
+## Enforce File Sizes
+
+Set `max_file_size` including the unit (bytes, kb, mb, gb, tb). Default is `5mb`. An error is shown if a file exceeds it.
```blade
-
-{{-- total size limit across all selected files --}}
-
```
-## File Type Restrictions
+For multiple files, set `max_total_file_size` to restrict the combined size regardless of individual file sizes.
+
+### Error Messages
+
+Customize the messages shown when a file exceeds the allowed size using `max_file_size_exceeded_label` and `max_file_size_label`.
+
+## Enforce File Types
+
+Set `accepted_file_types` to a comma-separated list of MIME types and/or file extensions (extensions need the dot prefix), e.g. `accepted_file_types="image/*, .pdf, .xlsx"`.
```blade
```
-## Multiple Files
+## Select Multiple Files
+
+By default only one file can be selected (`max_files="1"`). Set `max_files` higher to allow more. The placeholder stays visible until the maximum is reached; delete a file to select a new one.
```blade
@@ -78,110 +118,272 @@ For a fully custom placeholder layout, define a hidden `div` with class `placeho
## Image Manipulation
+These features are only exposed when `accepted_file_types` contains image MIME types.
+
+### Image Preview
+
+Enabled by default. Toggle with `show_image_preview`. If the selection mixes images and non-images, only images get previews.
+
```blade
-{{-- disable image preview --}}
+```
-{{-- enable cropping --}}
+### Image Cropping
+
+Disabled by default. Set `can_crop="true"` to enable (integrates Cropper.js).
+
+```blade
+```
-{{-- cropping with aspect ratio --}}
-
+Set `crop_aspect_ratio` to `16:9` (default), `4:3`, `2:3`, `1:1`, or `free` (lets the user drag the cropper freely).
-{{-- resize in background before upload --}}
-
+```blade
+
```
-Available `crop_aspect_ratio` values: `16:9` `4:3` `2:3` `1:1` `free`
+Clicking Cancel on the Cropper popup cancels only the crop, not the file selection.
+
+### Image Resizing
+
+No visual elements — this provides Filepond with resize instructions before upload. Set `can_resize="true"` and specify `image_resize_width` and/or `image_resize_height`.
+
+## Upload Selected Files to a Server
+
+Files can upload automatically on selection, or manually when the user submits a form. Manual is the default.
+
+### Automatically Upload Selected Files
-## Automatic Upload
+Set `auto_upload="true"` and `upload_route` to the route handling uploads (uses `POST` by default; override with `upload_method`). Uploaded files can be deleted via the trash icon — the delete route defaults to the upload route, override with `delete_route` (and `delete_method`, default `POST`). Additional headers can be set via `upload_headers` and `delete_headers` (an array); `delete_headers` defaults to `upload_headers` unless set explicitly.
```blade
+ delete_route="/upload-delete" />
```
-The upload route receives a POST request. The delete route is called when a user removes an uploaded file, also via POST. The component passes `{ "path": "path/to/file" }` when deleting.
+```php
+$headers = [
+ "Authorization" => "Bearer 67e518a8205b20.18576843",
+]
+```
```php
// web.php
Route::post('/upload', [FileUploadController::class, 'upload']);
Route::post('/upload-delete', [FileUploadController::class, 'delete']);
+
+// if you set delete_method="DELETE" and delete_route="/upload" on the component
+// your route will then look like the line below
+Route::delete('/upload', [FileUploadController::class, 'delete']);
```
-## Manual Upload (Form Submission)
+A barebones controller implementation:
-Manual upload is the default. Use an array name for multiple files. Add `enctype="multipart/form-data"` to the form.
+```php
+// FileUploadController.php
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+
+class FileUploadController extends Controller
+{
+ public function upload(Request $request)
+ {
+ $request->validate([
+ 'auto_upload' => 'required|mimes:jpg|max:1024',
+ ]);
+
+ $path = $request->file('auto_upload')->store('uploads', 'public');
+
+ return response()->json(['path' => $path]);
+ }
+
+ public function delete(Request $request)
+ {
+ // path: will always contain the path to the file being deleted
+ $filePath = $request->input('path');
+
+ if (!$filePath) {
+ return response()->json(['error' => 'No file path provided'], 400);
+ }
+
+ if (Storage::disk('public')->exists($filePath)) {
+ Storage::disk('public')->delete($filePath);
+ return response()->json(['message' => 'File deleted']);
+ }
+ return response()->json(['error' => 'File not found'], 404);
+ }
+}
+```
+
+When deleting a file, the component posts `{ "path" : "path/to/the/file-name-dot-extension" }`.
+
+### Manually Upload Selected Files
+
+The default behaviour. `upload_route` and `upload_method` are ignored since the FORM tag itself handles uploading — remember `enctype="multipart/form-data"` on the form. For multiple manual uploads, the `name` needs to be an array, e.g. `name="idCards[]"`.
```blade
```
-## Base64 Encoding
+```php
+// web.php
+Route::post('/manual-upload', [FileUploadController::class, 'manual_upload']);
+```
-```blade
-
+```php
+// FileUploadController.php
+public function manual_upload(Request $request)
+{
+ $request->validate([
+ 'files.*' => 'mimes:jpg|max:1024',
+ ]);
+
+ $uploadedFiles = [];
+ foreach ($request->file('manual_upload') as $file) {
+ $path = $file->store('uploads', 'public');
+ $uploadedFiles[] = $path;
+ }
+ dd($uploadedFiles);
+}
```
-The base64 data is written to an input named `attachments_b64`. Use `base64_output="string"` or `base64_output="url"` (default) to control the format.
+### Encode Files as base64
-## Edit Mode (Preloading Files)
+Works for single or multiple files. Set `base64="true"`; the base64 field name has `_b64` appended (e.g. `attachment` becomes `attachment_b64`). Set `base64_output` to `string` or `url` (default) to control the returned format.
+
+| Value | Sample Output |
+|---|---|
+| `string` | /9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAA ... |
+| `url` | data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX ... |
```blade
-@php
+
+```
+
+```php
+// web.php
+Route::post('/base64-upload', [FileUploadController::class, 'base64_upload']);
+```
+
+```php
+// FileUploadController.php
+public function base64_upload(Request $request)
+{
+ $base64Files = $request->input('attachments_b64');
+ foreach ($base64Files as $file) {
+ dump($file);
+ }
+}
+```
+
+Both the selected files and their base64-encoded versions are available on submission — use either or both.
+
+## Preloading Component with Specific Files (Edit Mode)
+
+Prepopulate with previously selected files so users can remove or add new ones, using the `selected_value` attribute.
+
+```php
$existingFiles = [
- [ 'source' => asset('images/photo1.jpg') ],
- [ 'source' => asset('images/photo2.jpg') ],
+ [ 'source' => asset('images/yoonbae-cho-Fes4eLW4mg0-unsplash.jpg') ],
+ [ 'source' => asset('images/sam-carter-JU1SVl4smHM-unsplash.jpg') ],
+ [ 'source' => asset('images/lissete-laverde-z9Ropm8edsw-unsplash.jpg') ],
];
-@endphp
+```
-
+```blade
+
```
+Even though `$existingFiles` has 3 elements, only 2 display because `max_files="2"`. Either raise `max_files` to match the array size, or remove it entirely, to load all files.
+
+## Laravel Form State
+
+When validation fails, Laravel redirects back with the submitted values flashed to the session and the messages in `$errors`. The Filepicker component reads the error half for you.
+
+```blade
+
+```
+
+`show_validation_error` gives the field its error state and renders `$errors->first()` underneath it. Add `error_bag` if you validate into a named bag. There is no `fill_from_old` — a file input cannot be repopulated by the browser for security reasons.
+
+Both are off by default. If your form already prints its own validation messages, switching this on without removing them would print every message twice.
+
+### Turning It On for Every Form
+
+```php
+// config/bladewind.php
+'forms' => [
+ 'fill_from_old' => true,
+ 'show_validation_error' => true,
+ 'error_bag' => null,
+],
+```
+
+An attribute on a single field always wins over the config, so you can opt one field out with `show_validation_error="false"`.
+
## Attributes
| Attribute | Default | Description |
|---|---|---|
-| name | random | Name for the file input field |
-| accepted_file_types | image/\*, audio/\*, video/\*, application/pdf | MIME types or file extensions (comma-separated) |
-| placeholder_line1 | Choose files or drag and drop to upload | First line of placeholder text |
-| placeholder_line2 | %s up to %s | Second line of placeholder text. `%s` is replaced with file types and max size |
-| selected_value | [] | Array of `{ source: url }` objects to preload in edit mode |
-| required | false | Append asterisk to placeholder. `true` \| `false` |
-| can_browse | true | Allow click-to-browse. `true` \| `false` |
-| can_drop | true | Allow drag-and-drop. `true` \| `false` |
+| name | random | Name for the filepicker, e.g. `profile_pic` renders `
`. |
+| accepted_file_types | image/*, audio/*, video/*, application/pdf | Comma-separated MIME types and/or file extensions. |
+| placeholder_line1 | Choose files or drag and drop to upload | Placeholder text on line 1. |
+| placeholder_line2 | %s up to %s | Placeholder text on line 2. |
+| selected_value | [] | Array of file names/sources to preload in edit mode. |
+| required | false | Append an asterisk to the placeholder text. `true` \| `false` |
+| can_browse | true | Allow launching the native file browser. `true` \| `false` |
+| can_drop | true | Allow selecting files by dropping them on the filepicker. `true` \| `false` |
| disabled | false | Disable the filepicker. `true` \| `false` |
-| max_files | 1 | Maximum number of files the user can select |
-| max_file_size | 5mb | Max size per file (include unit: `kb`, `mb`, `gb`) |
-| max_total_file_size | null | Max total size across all selected files |
-| validate_file_size | true | Validate file sizes. `true` \| `false` |
-| add_new_files_to | top | Where to insert newly added files. `top` \| `bottom` |
-| auto_upload | false | Automatically upload on selection. `true` \| `false` |
-| upload_route | null | URL for automatic uploads (POST) |
-| upload_method | POST | HTTP method for uploads. `POST` \| `PUT` \| `PATCH` |
-| upload_headers | [] | HTTP headers for upload requests |
-| delete_route | null | URL for deletion of uploaded files |
-| delete_method | null | HTTP method for deletion. Defaults to `upload_method` |
-| delete_headers | null | HTTP headers for delete requests. Defaults to `upload_headers` |
-| show_image_preview | true | Show image previews. `true` \| `false` |
-| can_crop | false | Enable image cropping. `true` \| `false` |
-| crop_aspect_ratio | 16:9 | Cropping aspect ratio. `16:9` \| `4:3` \| `2:3` \| `1:1` \| `free` |
-| can_resize_image | false | Resize image before upload (no UI). `true` \| `false` |
-| image_resize_width | null | Target width for resizing |
-| image_resize_height | null | Target height for resizing |
+| validate_file_size | true | Validate selected file sizes against `max_file_size`. `true` \| `false` |
| base64 | false | Generate base64 versions of selected files. `true` \| `false` |
-| base64_output | url | Format of base64 output. `url` \| `string` |
+| base64_output | url | Format for base64 output. `url` \| `string` |
| show_credits | false | Show Filepond credits. `true` \| `false` |
-| nonce | null | Nonce value for Content Security Policy |
+| auto_upload | false | Automatically upload files once selected. `true` \| `false` |
+| max_files | 1 | How many files the user can select. Positive integer. |
+| max_file_size | 5mb | Maximum size per file, including unit of measure. |
+| add_new_files_to | top | Where new selections are placed when files already exist. `top` \| `bottom` |
+| max_total_file_size | null | Maximum combined size for all selected files, e.g. `1gb`. |
+| show_image_preview | true | Show previews for selected images. `true` \| `false` |
+| can_resize_image | false | Allow background image resizing (no UI controls). `true` \| `false` |
+| image_resize_width | null | Resize images to this width, maintaining aspect ratio (ignores height if set). Positive integer. |
+| image_resize_height | null | Resize images to this height, maintaining aspect ratio (ignores width if set). Positive integer. |
+| can_crop | false | Allow image cropping. `true` \| `false` |
+| crop_aspect_ratio | 16:9 | Aspect ratio for cropping. `16:9` \| `4:3` \| `2:3` \| `1:1` \| `free` |
+| upload_route | null | URL for automatic file uploads. |
+| upload_headers | [] | HTTP headers appended when calling `upload_route`. |
+| upload_method | POST | HTTP method for automatic uploads. `POST` \| `PUT` \| `PATCH` |
+| delete_route | null | URL for deleting automatically uploaded files. |
+| delete_headers | null | HTTP headers appended when calling `delete_route`. Defaults to `upload_headers`. |
+| delete_method | null | HTTP method for deleting uploaded files. Defaults to `upload_method`. `POST` \| `DELETE` |
+| nonce | null | Nonce value for content security policies applied to inline scripts. Can also be set globally via `config/bladewind.php` under the "script" key. |
+| show_validation_error | false | Give the field its error state and render `$errors->first()` beneath it. Defaults to `bladewind.forms.show_validation_error`. `true` \| `false` |
+| error_bag | null | Which error bag to read when `show_validation_error` is on. Leave unset for Laravel's default bag. |
## Full Example
@@ -192,13 +394,15 @@ $existingFiles = [
placeholder_line1="Choose a profile picture"
placeholder_line2="Only jpg files allowed"
accepted_file_types=".jpg, .png"
+ selected_value=""
disabled="false"
base64="false"
base64_output="string"
can_crop="false"
- can_drop="true"
+ can_drop="false"
can_browse="true"
validate_file_size="true"
+ show_credits="true"
auto_upload="true"
max_files="2"
max_file_size="1mb"
@@ -207,6 +411,8 @@ $existingFiles = [
show_image_preview="true"
can_resize_image="true"
image_resize_width="1024"
+ image_resize_height=""
+ crop_aspect_ratio="free"
upload_route="/dp/upload"
upload_method="PATCH"
:upload_headers="$headers"
@@ -214,3 +420,9 @@ $existingFiles = [
delete_method="DELETE"
:delete_headers="$headers" />
```
+
+To avoid erratic behaviour when using multiple Filepickers on the same page, give each one a unique `name`.
+
+## Using Filepicker Inside Livewire
+
+The component guards against a Livewire re-render building a second FilePond instance (and a second Cropper.js instance when cropping is enabled) around the same field. When base64 mode is used, the hidden field created for each file dispatches a real, native `change` event, so Livewire's `wire:model` picks it up. FilePond manages its own DOM while a file is being added, cropped, or uploaded — wrap the picker in `wire:ignore` if it sits inside a Livewire component that can re-render for unrelated reasons during that time.
diff --git a/mcp/horizontal-line-graph.md b/mcp/horizontal-line-graph.md
index 7dc765bc..805ec9a1 100644
--- a/mcp/horizontal-line-graph.md
+++ b/mcp/horizontal-line-graph.md
@@ -6,14 +6,12 @@ url: /component/horizontal-line-graph
# Horizontal Line Graph
-Displays a labelled horizontal bar filled to a given percentage. Structurally similar to — and rendered using — the [Progress Bar](/component/progress-bar) component. The default colour is blue.
+Structurally similar to the Progress Bar component (it's rendered using it). The default colour is blue.
## Basic Usage
```blade
-
+
```
## Practical Example
@@ -25,7 +23,6 @@ Displays a labelled horizontal bar filled to a given percentage. Structurally si
-
{
(validateForm('.signup-form')) ?
- unhide('.btn-save .bw-spinner') :
- hide('.btn-save .bw-spinner');
+ unhide('.btn-save .bw-spinner') : // do this if validated
+ hide('.btn-save .bw-spinner'); // do this if not validated
}
```
-## Manipulating Inputs Using Javascript
+## Manipulating Inputs Using JavaScript
-There are several instances where you will want to manipulate input fields for different reasons. Most times, manipulating an input field will be dependent on a user's selection. This can be achieved in Javascript since BladewindUI uses the `name` attribute defined on an input as part of its `class` attribute.
+BladewindUI uses the `name` attribute defined on an input as part of its `class` attribute, making it easy to target fields in JavaScript based on user selections.
-The name you provided to the Input component has been used as part of the `class` names of the component. This makes it easy for you to access the component in Javascript.
+For example, a form that only reveals guardian fields for users under 18:
```blade
@@ -259,6 +250,19 @@ The name you provided to the Input component has been used as part of the `class
```
+The rendered `age_camp` input carries the name in its class, so it can be targeted directly:
+
+```blade
+
+```
+
```js
// domEl, unhide and hide are helper functions in BladewindUI
domEl('.age_camp').addEventListener('keyup', (el) => {
@@ -276,33 +280,26 @@ showAddress = (value) => {
}
```
-To manipulate BladewindUI input elements using Javascript, simply target them using the name defined either in the class or id attributes.
+To manipulate BladewindUI input elements using JavaScript, target them using the name defined either in the class or id attributes.
## Prefixes and Suffixes
-There are cases where you need to prefix or append something to an input field. For example, you want to prefix a URL input field with 'https://' so your users wouldn't need to type that in every time. Or, when asking your app users for their social media handles you may want to always have the '@' prefix. For now prefixes and suffixes support only text and [icons](/component/icon).
+Prefix or append content to an input field, for example a `https://` prefix on a URL field, or an `@` prefix for social handles. Prefixes and suffixes support text and [icons](/component/icon).
### Prefixes
-You can use prefixes even when your input has a label.
+Prefixes work even when the input has a label.
```blade
```
-```blade
-
-```
-
-```blade
-
-```
+They also work with a placeholder instead of a label.
```blade
+
+
-```
-
-```blade
```
@@ -312,9 +309,7 @@ Suffixes get appended to the end of the input field.
```blade
-```
-```blade
-```
-```blade
-```
-```blade
+
+
+
+
+ Sign Up
+
+```
+
+An SVG tag or custom SVG file can be used as the icon directly:
+
+```blade
+ prefix='
+ ' />
```
## Clearable Inputs
-Clearable fields display an x icon when a field has a value entered. Clicking on the x icon deletes the text in the input field. Quite handy and saves users from clicking the backspace several times in say, a search field. This is achieved by setting the `clearable="true"` attribute. If there is a table that shares the same name as the input field, it will be reset as well.
+Clearable fields display an x icon when the field has a value; clicking it clears the text. Set `clearable="true"`. If a table shares the same name as the input, it is reset as well, useful for searchable [tables](/component/table#searchable).
```blade
@@ -396,63 +407,88 @@ Clearable fields display an x icon when a field has a value entered. Clicking on
## Input Field Sizes
-The input field comes in sizes to match the various button sizes. This is useful if you wish to have an input field and a button on one line. Set the `size` attribute to achieve this. The `tiny` size is not supported for input fields.
+The input comes in sizes matching the various button sizes, useful for putting an input and a button on one line. Set the `size` attribute. The `tiny` size is not supported for inputs.
```blade
-```
-
-```blade
+
+
```
+## Laravel Form State
+
+When validation fails, Laravel redirects back with submitted values flashed to the session and messages in `$errors`. The Input component can read both, avoiding manual `old('...')` and error blocks on every field.
+
```blade
-
+
```
-```blade
-
+`fill_from_old` repopulates the field from `old()`. `show_validation_error` gives the field its error state and renders `$errors->first()` underneath it. Add `error_bag` if validating into a named bag.
+
+Both are off by default. If your form already prints its own validation messages, switching this on without removing them prints every message twice.
+
+### Turning It On For Every Form
+
+Rather than setting attributes field by field, set them once in `config/bladewind.php` and every form component follows.
+
+```php
+// config/bladewind.php
+'forms' => [
+ 'fill_from_old' => true,
+ 'show_validation_error' => true,
+ 'error_bag' => null,
+],
```
+An attribute on a single field always wins over the config, so a field can opt out with `show_validation_error="false"`.
+
## Attributes
| Attribute | Default | Description |
|---|---|---|
-| name | input-uniqid() | Unique name to identify the input element by. Useful for retrieving value from the input when it is submitted in a form. |
-| type | text | Accepts list of valid HTML input element types. `text` \| `email` \| `password` \| `search` \| `tel` |
-| label | _(blank)_ | Label that describes the input element. Example: Full name |
-| numeric | false | Specifies if the input element should accept only numeric characters. `true` \| `false` |
-| required | false | Specifies if the input element is required or not. When required, a red asterisk is displayed next to the placeholder or label. `true` \| `false` |
-| add_clearing | true | Specifies if an 8px margin should be added to the bottom of the element. `true` \| `false` |
-| placeholder | _(blank)_ | Placeholder text to display in the input element. |
-| show_placeholder_always | false | Placeholder text is hidden when the label attribute has a value. Setting this to true always shows the placeholder. `true` \| `false` |
-| error_message | _(blank)_ | The message to display when the form is validated and field happens to be blank. |
-| show_error_inline | false | Error messages can either be displayed inline or using the Notification component (default). `true` \| `false` |
-| error_heading | Error | Only used when displaying validation errors using the Notification component. Provides a way to specify a translatable heading for the error. |
-| selected_value | _(blank)_ | Default value to display in the input element. Useful when in edit mode. |
-| with_dots | true | Mostly relevant if `numeric="true"`. Determines if numeric values can contain dots or not. `true` \| `false` |
-| mask | _(blank)_ | Static mask template using the wildcards `9` (digit), `a` (letter) and `*` (alphanumeric). Every other character is a literal that is inserted automatically. e.g. `mask="(999) 999-9999"`. |
-| dynamicMask | null | A dynamic mask for formats that change as the user types. Use the built-in `creditCard`, or the name of your own global JavaScript function that receives the current value and returns a mask template. |
-| money | false | Format the field as a money input — groups thousands and fixes the decimal places. `true` \| `false` |
-| moneyDecimalSeparator | . | Character used to separate the decimal part when `money="true"`. |
-| moneyThousandsSeparator | , | Character used to group thousands when `money="true"`. |
-| moneyPrecision | 2 | Number of decimal places allowed when `money="true"`. Set to `0` to disable decimals. |
-| prefix | blank | Specify the prefix for the input field. |
-| prefix_is_icon | false | If prefix is specified, is it an icon. By default prefixes are treated as text. `true` \| `false` |
-| prefix_icon_type | outline | If an icon is used as a prefix, should it be a solid or outline icon. `outline` \| `solid` |
-| transparent_prefix | true | If a prefix is defined, should it have a transparent background or not. `true` \| `false` |
-| prefix_icon_div_css | blank | Additional css classes to apply to the DIV containing the prefix if **prefix_is_icon=true**. |
-| prefix_icon_css | blank | Additional css classes to apply to the prefix if **prefix_is_icon=true**. |
-| suffix | blank | Specify the suffix for the input field. |
-| suffix_is_icon | false | If suffix is specified, is it an icon. By default suffixes are treated as text. `true` \| `false` |
-| suffix_icon_type | outline | If an icon is used as a suffix, should it be a solid or outline icon. `outline` \| `solid` |
-| transparent_suffix | true | If a suffix is defined, should it have a transparent background or not. `true` \| `false` |
-| suffix_icon_div_css | blank | Additional css classes to apply to the DIV containing the suffix if **suffix_is_icon=true**. |
-| suffix_icon_css | blank | Additional css classes to apply to the suffix if **suffix_is_icon=true**. |
-| viewable | false | Works only if **type=password**. Should the password be viewable? If `true`, an eye icon is displayed. `true` \| `false` |
-| clearable | false | Appends an 'x' circle for clearing any text that has been entered in the input field. `true` \| `false` |
-| size | medium | Sizing of the input to match button sizes. `small` \| `regular` \| `medium` \| `big` |
-| nonce | null | Used when implementing context security policies and require to pass a nonce to inline scripts. |
+| name | input-uniqid() | Unique name to identify the input element by. Useful for retrieving the value when the form is submitted. Defaults to a random name prefixed with `input-`. |
+| type | text | Valid HTML input element types, e.g. `text` \| `email` \| `password` \| `search` \| `tel`. |
+| label | blank | Label that describes the input element. |
+| numeric | false | Restrict the input to numeric characters only. `true` \| `false` |
+| required | false | Whether the field is required. Displays a red asterisk next to the placeholder or label. `true` \| `false` |
+| add_clearing | true | Add an 8px bottom margin so form fields are evenly spaced by default. `true` \| `false` |
+| placeholder | blank | Placeholder text. |
+| show_placeholder_always | false | Placeholder is normally hidden when `label` has a value; set true to always show it. `true` \| `false` |
+| error_message | blank | Message shown when the form is validated and the field is blank. |
+| show_error_inline | false | Display error messages inline instead of via the Notification component (default). `true` \| `false` |
+| error_heading | Error | Translatable heading for the error, used only when displaying validation errors via the Notification component. |
+| selected_value | blank | Default value for the input, useful in edit mode. |
+| with_dots | true | Relevant when `numeric="true"`. Whether numeric values may contain dots. `true` \| `false` |
+| mask | blank | Static mask template using wildcards `9` (digit), `a` (letter), `*` (alphanumeric). Example: `mask="(999) 999-9999"`. |
+| dynamicMask | null | Dynamic mask for formats that change as the user types. Use the built-in `creditCard`, or the name of a global JS function returning a mask template. |
+| money | false | Format the field as a money input, grouping thousands and fixing decimal places. `true` \| `false` |
+| moneyDecimalSeparator | . | Character separating the decimal part when `money="true"`. |
+| moneyThousandsSeparator | , | Character grouping thousands when `money="true"`. |
+| moneyPrecision | 2 | Number of decimal places when `money="true"`. Set to `0` to disable decimals. |
+| prefix | blank | Prefix for the input field. |
+| prefix_is_icon | false | Whether `prefix` is an icon rather than text. `true` \| `false` |
+| prefix_icon_type | outline | Style of icon used as a prefix. `outline` \| `solid` |
+| transparent_prefix | true | Whether the prefix has a transparent background. `true` \| `false` |
+| prefix_icon_div_css | blank | Additional CSS classes for the DIV containing the prefix when `prefix_is_icon=true`. |
+| prefix_icon_css | blank | Additional CSS classes for the prefix icon when `prefix_is_icon=true`. |
+| suffix | blank | Suffix for the input field. |
+| suffix_is_icon | false | Whether `suffix` is an icon rather than text. `true` \| `false` |
+| suffix_icon_type | outline | Style of icon used as a suffix. `outline` \| `solid` |
+| transparent_suffix | true | Whether the suffix has a transparent background. `true` \| `false` |
+| suffix_icon_div_css | blank | Additional CSS classes for the DIV containing the suffix when `suffix_is_icon=true`. |
+| suffix_icon_css | blank | Additional CSS classes for the suffix icon when `suffix_is_icon=true`. |
+| viewable | false | Works only if `type=password`. Show an eye icon to reveal the password. `true` \| `false` |
+| clearable | false | Appends an 'x' circle suffix to clear the entered text. `true` \| `false` |
+| size | medium | Sizing to match button sizes. `small` \| `regular` \| `medium` \| `big` |
+| nonce | null | Nonce for content security policies on inline scripts. Can also be set globally via `config/bladewind.php` under `script`. |
+| fill_from_old | false | Repopulate the field from `old()` after a failed Laravel validation redirect. Defaults to `bladewind.forms.fill_from_old`. `true` \| `false` |
+| show_validation_error | false | Give the field its error state and render `$errors->first()` beneath it. Defaults to `bladewind.forms.show_validation_error`. `true` \| `false` |
+| error_bag | null | Error bag to read from when `show_validation_error` is on. Leave unset for Laravel's default bag. |
## Full Example
diff --git a/mcp/kanban.md b/mcp/kanban.md
new file mode 100644
index 00000000..ad4b61f3
--- /dev/null
+++ b/mcp/kanban.md
@@ -0,0 +1,104 @@
+---
+title: Kanban Component
+component: x-bladewind::kanban
+url: /component/kanban
+---
+
+# Kanban
+
+`x-bladewind::kanban`, `x-bladewind::kanban.column` and `x-bladewind::kanban.card` build a board of columns holding draggable cards, the pattern behind any task tracker. A card can be dragged with the mouse or a touch screen between columns and within a column, or moved the same way with the keyboard: focus a card and use the arrow keys, up and down to reorder within a column, left and right to move it into the column beside it.
+
+```blade
+
+
+ Design the onboarding flow
+ Write the API documentation
+
+
+ Build the payments webhook
+
+
+ Set up the staging environment
+
+
+```
+
+## Reacting To A Move
+
+Set `on_move` on the board to the name of a JavaScript function. It is called after every move, whether by drag or by keyboard, as `(cardId, fromColumnId, toColumnId, newIndex)`. Use it to save the new position with a request to your backend.
+
+```blade
+
+ ...
+
+
+
+```
+
+## Empty State
+
+A column with no cards shows a short message instead of a blank space. Customise it with `empty_text`.
+
+```blade
+
+
+```
+
+## Loading State
+
+Set `loading="true"` on a column while its cards are still being fetched. It shows a spinner in place of the card list.
+
+```blade
+
+
+```
+
+## Column Actions
+
+Give a column an `actions` slot for a control shown beside its title, such as an add-card button.
+
+```blade
+
+
+
+
+
+ Design the onboarding flow
+
+```
+
+## Attributes
+
+### Kanban
+
+| Attribute | Default | Description |
+|---|---|---|
+| animation | 150 | Animation speed in milliseconds when a card is dropped. 0 disables it. |
+| on_move | _blank_ | Name of a JavaScript function called after every move as `(cardId, fromColumnId, toColumnId, newIndex)`. |
+| class | _blank_ | Additional CSS classes for the board's wrapper element. |
+
+### Column
+
+| Attribute | Default | Description |
+|---|---|---|
+| title | _blank_ | The column's heading. |
+| id | a slug of the title | Identifier reported to the move hook. Set it explicitly when the title alone is not a stable, unique key. |
+| loading | false | Hides the card list and shows a spinner instead. `true` \| `false` |
+| empty_text | No cards | Shown in place of the list when it has no cards and is not loading. |
+| actions | _none_ | A named slot rendered beside the title. |
+| class | _blank_ | Additional CSS classes for the column. |
+
+### Card
+
+| Attribute | Default | Description |
+|---|---|---|
+| value | _blank_ | Identifier reported to the move hook, for example a model id. |
+| class | _blank_ | Additional CSS classes for the card. |
diff --git a/mcp/kbd.md b/mcp/kbd.md
new file mode 100644
index 00000000..a3fc8b28
--- /dev/null
+++ b/mcp/kbd.md
@@ -0,0 +1,43 @@
+---
+title: Keyboard Key Component
+component: x-bladewind::kbd
+url: /component/kbd
+---
+
+# Keyboard Key
+
+`x-bladewind::kbd` renders a semantic `
` element styled as a physical key — for documenting a shortcut in help
+text, a menu item, or command documentation.
+
+## Basic Usage
+
+```blade
+Press Esc to close.
+```
+
+## Key combinations
+
+Pass `keys` as an array (or JSON string) to render a combo — each key in its own pill, joined by "+". When `keys` is
+given, it takes priority over the default slot.
+
+```blade
+Tab
+Tab
+Tab
+```
+
+## Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| keys | _(none)_ | Array or JSON string of key labels for a combo. Takes priority over the default slot. |
+| size | small | `tiny` \| `small` \| `regular` |
+| class | _(blank)_ | Additional CSS classes for the key (or the combo's wrapper, when using `keys`). |
diff --git a/mcp/meter.md b/mcp/meter.md
new file mode 100644
index 00000000..676c719a
--- /dev/null
+++ b/mcp/meter.md
@@ -0,0 +1,56 @@
+---
+title: Meter Component
+component: x-bladewind::meter
+url: /component/meter
+---
+
+# Meter
+
+`x-bladewind::meter` visualises a bounded measurement — disk usage, a score, a signal strength — as opposed to
+Progress Bar's task completion. Give it `low` and `high` boundaries and it colours itself semantically: green for
+the good zone, red for the bad one, yellow for the zone in between. A real, visually hidden `` element
+carries the actual accessible semantics; the coloured bar is purely decorative.
+
+## Basic Usage
+
+```blade
+
- Basic modal
-
-
-
- Basic modal with a title
-
+Basic modal
-
- Please agree to the terms and conditions of
- the agreement before proceeding.
+
+ Please agree to the terms and conditions of the agreement before proceeding.
-
- Please agree to the terms and conditions of
- the agreement before proceeding.
+Basic modal with a title
+
+
+ Please agree to the terms and conditions of the agreement before proceeding.
```
-## Different Types
+Modals are targeted and invoked using the `name` attribute. Several modals can exist on the same page, but each must have a unique name.
-The BladewindUI modal component comes prebuilt with some default types for the common use cases. This can be achieved by setting the `type` attribute on the modal component. The default `type=""`. All the type attribute does is append the appropriate icons that match the type of modal.
+Clicking the backdrop or the cancel button dismisses the modal by default. This can be prevented; see [Non-Dismissible Modal](#non-dismissible-modal).
-### Info Modal
+## Different Types
-Set `type="info"` on the modal component. The default icon changes to a blue info icon.
+Set `type` to append icons matching common use cases: `info`, `error`, `warning`, `success`. The default is blank (no type icon).
```blade
-
- Info Modal
-
-
-
- We really think you should buy some Bitcoin
- despite it's ups and downs. What sayeth thou?
+
+ We really think you should buy some Bitcoin despite its ups and downs. What sayeth thou?
-```
-
-### Error Modal
-
-Set `type="error"` on the modal component. The default icon changes to a red exclamation mark.
-
-```blade
-
- Error Modal
-
-
+
You do not have permissions to delete this user.
-```
-
-### Warning Modal
-
-Set `type="warning"` on the modal component. The default icon changes to a yellow bell icon.
-
-```blade
-
- Warning Modal
-
-
- Hmmm...This is your first warning.
- Two more warnings and you are off this platform.
+
+ Hmmm...This is your first warning. Two more warnings and you are off this platform.
-```
-
-### Success Modal
-
-Set `type="success"` on the modal component. The default icon changes to a green thumbs up icon.
-
-```blade
-
- Success Modal
-
-
+
Yayy.. User deleted successfully
```
### Stretched Action Buttons
-Some users prefer to have their action buttons span the entire width of the modal. Set `stretched_action_buttons="true"` on the modal component.
+Set `stretch_action_buttons="true"` to make each action button span the full width of the modal, each on its own line.
```blade
-
- Stretched Buttons Modal
-
-
-
- The action buttons in this modal have been stretched.
- This means each button gets its own line.
+
+ The action buttons in this modal have been stretched. This means each button gets its own line.
```
## Backdrop Blur Intensity
-The backdrop can be customized to have different intensities of the blur by specifying `blur_size`. The available values are `none`, `small`, `medium`, `large`, `xl`, `xxl`, `omg`.
+The backdrop blur can be customized with `blur_size`: `none`, `small`, `medium`, `large`, `xl`, `xxl`, `omg`.
```blade
-
- No Blur
-
+
+ The backdrop of this modal is not blurred. You can see all the content behind the backdrop.
+
-
- The backdrop of this modal is not blurred.
- You can see all the content behind the backdrop.
+
+ A much more intense blur.
```
## Using Different Icons
-The default types use predefined icons. You may want to use your own icons in the modal component. Set the `icon` attribute to any icon name on [Heroicons](https://heroicons.com). This modal icon is displayed using the BladewindUI [Icon](/component/icon) component. Use the `icon_css` attribute to apply extra styling to the custom icon.
+Set `icon` to any [Heroicons](https://heroicons.com) name to display a custom icon via the BladewindUI [Icon](/component/icon) component, and pair it with `icon_css` for extra styling.
```blade
-
- Custom Icon Modal
-
-
```
-You may want to use a custom icon but with one of the predefined states. Simply set both the `type` and `icon` attributes.
+A custom icon can also be combined with one of the predefined `type` states by setting both `type` and `icon`:
```blade
On mobile the modal has just one size.
-
-The BladewindUI modal component comes with a size option that allows your content to breathe in the modals. Set the `size` attribute on the modal component. The default `size="small"`. All sizes are the same on mobile.
+On mobile the modal always renders at a single size. Set `size` to control desktop width. Default is `big`.
| Size | CSS Class |
|---|---|
-| tiny | `sm:w-72` |
-| small | `sm:w-96` |
-| medium | `sm:w-[32rem]` |
-| large | `sm:w-[60rem]` |
-| xl | `sm:w-[86rem]` |
-| omg | `max-w-screen` |
+| tiny | sm:w-72 |
+| small | sm:w-96 |
+| medium | sm:w-[32rem] |
+| large | sm:w-[60rem] |
+| xl | sm:w-[86rem] |
+| omg | max-w-screen |
```blade
-
- I am the tiniest in the modal family. Don't hate.
+
+ I am the tiniest in the modal family.
-
- I am the smallest in the modal family. Don't hate.
+
+ I am the smallest in the modal family.
-
+
I am the medium sized modal.
- Also the default if you do not set a size.
-
- I am the large modal. If I am not large enough to contain
- your needs, check out my xl brother.
+
+ I am the large modal.
-
+
I am the extra large modal.
-
- I am the full width modal. My nickname is OMG.
+
+ I am the full width modal. My nickname is OMG. I take up the entire screen.
```
## Action Buttons
-The modal component by default shows a `Cancel` and `Okay` button. Both buttons by default close the modal when clicked. It is possible to show either of the buttons or even none of the buttons.
+The modal shows a `Cancel` and `Okay` button by default; both close the modal when clicked. Either or both can be hidden or relabeled.
-If you don't want your buttons to say **Cancel** and **Okay**, set the `cancel_button_label` and `ok_button_label` attributes to whatever text you want the buttons to display.
-
-To hide the `cancel` button, set `cancel_button_label=""`. When the button label is blank, the button won't be displayed. To hide the okay button, set `ok_button_label=""`.
-
-### No Cancel Button
+Set `cancel_button_label` and `ok_button_label` to change button text. Setting either to an empty string hides that button.
```blade
-
- No cancel button
-
-
-
+
I have no cancel button. Just okay and that is fine.
-```
-
-### No Okay Button
-```blade
-
- No okay button
-
-
-
- I have no okay button.
- Just cancel this thing and let's all go home.
+
+ I have no okay button. Just cancel this thing and let's all go home.
```
### Hiding Both Action Buttons
-Set `show_action_buttons="false"` to hide both action buttons. A no-action-buttons modal can be useful if you want to have a form in a modal with its own button that submits the form.
+Instead of blanking both labels, set `show_action_buttons="false"`. Useful for a modal containing its own form with its own submit button.
```blade
-
- No action buttons
-
-
-
+
I have no action buttons. Only the backdrop can close me now.
```
### Action Button Actions
-By default both action buttons close the modal. To change these default actions, set the `cancel_button_action` and `ok_button_action` attributes. The default values are `cancel_button_action="close"` and `ok_button_action="close"`. The attributes expect javascript functions as the values.
+By default both buttons close the modal (`cancel_button_action="close"` and `ok_button_action="close"`). Both attributes accept a JavaScript function to call instead. Set `close_after_action="false"` to keep the modal open after either button is clicked.
```blade
```
-By default, the modal is dismissed after clicking any of the action buttons. Setting `close_after_action="false"` will ensure the modal stays open after clicking any of the action buttons.
-
### Close Icon
-To close a modal using a close icon placed in the top right, set `show_close_icon="true"`.
+Closing is normally delegated to the Cancel/Close button in the footer. Set `show_close_icon="true"` to also show a close icon in the top-right corner of the modal.
### Alignment of the Action Buttons
-By default the action buttons are right aligned but left aligned if the modal `size="tiny"`. To change the alignment of the action buttons, set the `align_buttons` attribute to either `left`, `center` or `right`.
+Action buttons are right-aligned by default, or left-aligned when `size="tiny"`. Change alignment with `align_buttons`: `left`, `center`, `right`.
+
+```blade
+
+ Are you sure you want to delete this user? This action cannot be undone.
+
+```
## Non-Dismissible Modal
-By default the modal component can be closed using the backdrop or any of the action buttons. To prevent dismissal, set `backdrop_can_close="false"`. If you are using the modals with the action buttons you will also need to set the actions of each button.
+By default the modal can be closed via the backdrop or action buttons. Set `backdrop_can_close="false"` to prevent this until a choice is made or an action performed. If using action buttons, also set their actions explicitly (see [Action Buttons](#action-buttons)).
```blade
-
+lock the screen
+
-
You will need to unlock the screen to continue using this application.
-
- Check password
-
```
-## Submitting Form Using Action Button
+## Submitting a Form Using an Action Button
-### Validate and Submit Form
+There are three common ways to submit a form loaded inside a modal, only when validation passes.
-```blade
-// the modal and its form
-
+### Option 1: Validate and Submit
+Call `saveProfile()` from `ok_button_action`, keep the modal open with `close_after_action="false"`, and let the function validate then submit the form.
+
+```blade
+
