Skip to content
widgets / 1

JavaScript API

Last updated:

On this page

The package's TypeScript lives in resources/js and reaches your app as @javaabu/widgets through javaabu/manifest. It isn't on npm. The Blade admin script is also prebuilt in dist/ for apps without Vite.

Rendering widgets

import { WidgetLocation, Widget, registerWidgets, resolveWidget, builtInWidgets } from "@javaabu/widgets"
Export
<WidgetLocation name widgets components? wrapper? always? …divProps> A location's widgets, in the same markup as <x-widgets::location>
<Widget widget components? wrapper?> One widget in its <section> wrapper
registerWidgets(components) Register components by widget key or component name, for every location
registeredWidgets() The registered components, the built-ins included
resolveWidget(widget, components?) The component for a widget, or null
builtInWidgets { text: TextWidget, image: ImageWidget, link: LinkWidget }
TextWidget, ImageWidget, LinkWidget The built-in components
isSafeUrl(url), safeUrl(url), isExternalUrl(url), filled(value) Helpers the built-ins use

Types: WidgetData<Settings, Data>, WidgetLocations, WidgetComponentProps<Settings, Data>, WidgetComponent, WidgetComponents.

WidgetLocation, Widget and the built-in components import resources/css/widgets.css, so Vite bundles the widget styles with them. Your own widget components bring their own styles.

Admin pages

Export
WidgetsIndex The widgets::Widgets/Index page
WidgetsEdit The widgets::Widgets/Edit page
WidgetsLocationCard One location on the index page: the sortable list, edit and remove buttons, and the add form. onReorder(location, ids) saves the order.
SortableList<T> A list sorted by drag and drop or the keyboard, with a live region

Types: WidgetsIndexProps, WidgetsEditProps, WidgetLocationData, WidgetItemData, WidgetTypeData, WidgetsStrings.

SortableList

import { SortableList } from "@javaabu/widgets"

<SortableList
  items={items}
  getKey={(item) => item.id}
  getTitle={(item) => item.title}             // what screen readers call it
  strings={strings}                           // picked_up, moved, dropped, cancelled (":widget", ":position", ":total")
  instructionsId="widgets-instructions"       // the element that explains the keys
  onReorder={(items) => save(items.map((item) => item.id))}
  renderItem={(item, handle) => (
    <>
      <button type="button" {...handle} aria-label={`Move ${item.title}`}>⠿</button>
      {item.title}
    </>
  )}
/>

Spread handle on the drag handle. Only the handle starts a drag, so the rest of the item stays clickable. The keys are Space or Enter to pick up and drop, the arrow keys, Home and End to move, and Escape to cancel. disabled turns sorting off. New items from the server replace the local order.

Without React

import { createSortable, moveItem, announcement, keyboardTarget, format } from "@javaabu/widgets"

const sortable = createSortable(document.querySelector("ol")!, {
  itemSelector: "[data-widget-id]",          // the default
  handleSelector: "[data-widgets-handle]",   // the default
  announce: (message) => (liveRegion.textContent = message),
  onChange: (items) => save(items.map((item) => item.dataset.widgetId)),
})

sortable.destroy()

createSortable() moves the DOM elements themselves, so form inputs inside the items follow them. The Blade admin script (widgets::admin, resources/js/blade/admin.ts) uses it on every [data-widgets-sortable] list. It sends the surrounding form[data-widgets-order] with fetch after each drop, and fires a widgets:order event on [data-widgets-admin] with { saved, location }.

Documentation
All packages

javaabu/widgets

Source on GitHub