JavaScript Utilities
The JavaScript utilities are a set of methods that can be used to simplify the development process.
Copy to Clipboard
Copy text to the clipboard by using the window.copyToClipboard(idOrText) method.
If you want to copy the innerHTML of an element, pass the element's ID as the argument. The ID must start with a # symbol.
If you pass an id and it's an <code>-tag or the element has the attribute data-html-decode, the innerHTML will be html-decoded. That means, symbols like < will be converted to <.
1<x-button id="copy-btn">Copy</x-button> 2 3@script 4<script> 5document.getElementById('copy-btn').addEventListener('click', function() { 6 window.copyToClipboard('Basic-Components for Livewire is awesome.'); 7 // window.copyToClipboard('#copy-btn'); (Will copy the innerHTML of the element) 8 alert('Text copied to clipboard!'); 9});10</script>11@endscriptFocus Input
Use window.focusInput(domElementOrId) to focus an input element and set the cursor to the end of the text.
1<!-- Input -->2<x-input id="focus-input" value="Focus at the end" />3 4<!-- Button -->5<x-button x-on:click="window.focusInput('#focus-input')">Focus</x-button>Add Errors manually
You can change the state of any input element to an error state by using the window.addError(domElementOrId, message) method. Remove the error by using the window.removeError(domElementOrId) method.
1<x-input id="error-input" />2 3<x-button x-on:click="window.addError('#error-input', 'Add any error you want.')">Add Error</x-button>4<x-button x-on:click="window.removeError('#error-input')">Remove</x-button>Add Errors manually
You can change the state of any input element to an error state by using the window.addError(domElementOrId, message) method. Remove the error by using the window.removeError(domElementOrId) method.
Important: This will only add an error on the client-side, not in Livewire!
1<x-input id="error-input" />2 3<x-button x-on:click="window.addError('#error-input', 'Add any error you want.')">Add Error</x-button>4<x-button x-on:click="window.removeError('#error-input')">Remove</x-button>Disable / Enable Scrolling
If you want to disable scrolling on the body (e. G. for popups, modals, etc…), you can use the window.disableScrolling() and window.enableScrolling() methods. This method fixes the layout shift, which occurs when the browser scrollbar disappears.
1<x-button type="danger" x-on:click="window.disableScrolling(); toast.warning('Scrolling disabled.')">Disable Scrolling</x-button>2<x-button type="success" x-on:click="window.enableScrolling(); toast.success('Scrolling enabled.')">Enable Scrolling</x-button>Marquee (Auto-Scrolling Text)
The x-marquee Alpine directive automatically scrolls text when it overflows its container. If the text fits, nothing happens — it only activates when there's overflow. The marquee pauses on hover and responds to container resizes via ResizeObserver.
After 24 hours the marquee stops and the original content is restored. There is a 3-second pause between each scroll cycle (split between start and end).
1{{-- Basic marquee: scrolls automatically when text overflows --}}2<span x-marquee>3 This is a long text that will scroll automatically once it overflows its container.4</span>Marquee Speed Modifiers
Control the scroll speed using modifiers:
| Modifier | Speed | Description |
|---|---|---|
| x-marquee.slow | 20 px/s | Slow, subtle scrolling for background information. |
| x-marquee | 30 px/s | Default speed — balanced for most use cases. |
| x-marquee.fast | 50 px/s | Fast scrolling for attention-grabbing content. |
1{{-- Marquee with speed modifiers --}} 2 3{{-- Slow speed (20px/s) --}} 4<span x-marquee.slow> 5 A slow-scrolling marquee for subtle animations. 6</span> 7 8{{-- Default speed (30px/s) --}} 9<span x-marquee>10 Default speed marquee — 30 pixels per second.11</span>12 13{{-- Fast speed (50px/s) --}}14<span x-marquee.fast>15 A fast-scrolling marquee for attention-grabbing content.16</span>Marquee in Nav Items
A common use case: long labels inside nav items or table cells. Wrap the text in a <span x-marquee> to scroll only when the label overflows.
1{{-- Marquee inside a nav item or table cell --}}2<x-nav.item icon="bell-alert--outline">3 <span x-marquee.slow>New notification: Your order #12345 has been shipped and is on its way!</span>4</x-nav.item>Timeago (Relative Time)
The x-timeago Alpine directive converts an ISO 8601 datetime into a human-readable relative time string like "vor 5 Minuten" or "3 hours ago". It updates automatically every second and supports both past and future dates.
The directive auto-detects the language from <html lang="…">. Built-in languages: de (German) and en (English), with support for custom translations.
1{{-- Basic timeago: auto-detects language from <html lang="…"> --}}2<span x-timeago="2025-03-25T10:30:00Z">25. März 2025, 10:30</span>Timeago Language Override
Force a specific language using a modifier, regardless of the page's lang attribute:
1{{-- Timeago with explicit language modifier --}} 2 3{{-- Force German --}} 4<span x-timeago.de="{{ $post->created_at->toIso8601String() }}"> 5 {{ $post->created_at->format('d.m.Y H:i') }} 6</span> 7 8{{-- Force English --}} 9<span x-timeago.en="{{ $post->created_at->toIso8601String() }}">10 {{ $post->created_at->format('M d, Y H:i') }}11</span>Timeago Direction Modifiers
Restrict the directive to only format past or future dates. When the date doesn't match the direction, the original content is preserved.
| Modifier | Behavior |
|---|---|
| x-timeago.past | Only formats dates in the past. Future dates keep their original content. |
| x-timeago.future | Only formats dates in the future. Past dates keep their original content. |
| x-timeago (no modifier) | Formats both past and future dates (default). |
1{{-- Timeago with direction modifiers --}} 2 3{{-- Only format past dates (future dates keep their original content) --}} 4<span x-timeago.past="{{ $event->started_at->toIso8601String() }}"> 5 {{ $event->started_at->format('d.m.Y H:i') }} 6</span> 7 8{{-- Only format future dates (past dates keep their original content) --}} 9<span x-timeago.future="{{ $event->starts_at->toIso8601String() }}">10 {{ $event->starts_at->format('d.m.Y H:i') }}11</span>Timeago Custom Translations
Add or override translations by setting window.bcTimeagoTranslations before bcInitialize() runs. Your custom translations are merged with the built-in ones, so you only need to define what you want to add or change.
1{{-- Custom translations for timeago (place in app.js before bcInitialize) --}} 2window.bcTimeagoTranslations = { 3 fr: { 4 justNow: 'à l\'instant', 5 past: { prefix: 'il y a', suffix: '' }, 6 future: { prefix: 'dans', suffix: '' }, 7 seconds: { singular: '1 seconde', plural: '{{count}} secondes' }, 8 minutes: { singular: '1 minute', plural: '{{count}} minutes' }, 9 hours: { singular: '1 heure', plural: '{{count}} heures' },10 days: { singular: '1 jour', plural: '{{count}} jours' },11 weeks: { singular: '1 semaine', plural: '{{count}} semaines' },12 months: { singular: '1 mois', plural: '{{count}} mois' },13 years: { singular: '1 an', plural: '{{count}} ans' },14 },15};Logger (Dev-Only Logging)
This package includes a lightweight dev-only logger that wraps console methods. It uses Vite's import.meta.env.DEV flag to control output:
- log.log() — only outputs during npm run dev. In production builds (npm run build), these calls are completely tree-shaken and produce zero output.
- log.info() — always outputs, even in production.
- log.warn() — always outputs, even in production.
- log.error() — always outputs, even in production.
The logger is used internally by components like the Image Editor and Speech-to-Text to provide helpful debug output during development without polluting the browser console in production.
1import log from '@basic-components/js/utilities/logger'; 2 3const LOG_PREFIX = '[MyComponent]'; 4 5// Only outputs during `npm run dev` — completely removed in production builds 6log.log(LOG_PREFIX, 'Initializing component…', { foo: 'bar' }); 7 8// Always outputs, even in production 9log.info(LOG_PREFIX, 'Info message');10log.warn(LOG_PREFIX, 'Warning message');11log.error(LOG_PREFIX, 'Error message');