sodcalculator

10 Tech How-To

Accessible Laravel UI Components Without JavaScript

Guide 10-55505 · Updated · Step by step

This guide shows you how to build accessible Laravel UI components using only Blade templates, CSS, and the framework’s built-in features—no JavaScript framework required. You’ll create components that work for keyboard users, screen readers, and everyone else, while keeping your codebase simple and fast.

What You’ll Need

  • A Laravel application (version 8 or later recommended) with Blade templating set up
  • Basic familiarity with Blade components and slots
  • Comfort with HTML and CSS for styling and accessibility attributes
  • Optional: A local testing tool like Lighthouse or axe browser extension to verify accessibility

Step-by-Step

  1. Create a Blade component for a simple disclosure (accordion). Run php artisan make:component Disclosure to generate the class and view. This component will manage expand/collapse behavior using native HTML details and summary elements, which are inherently keyboard accessible.
  2. Define the component’s data and attributes. In the Disclosure class, add a public property for an ID (to link the button to the content) and a default open state. Use public $id; and public $open = false; in the constructor.
  3. Write the Blade view for the disclosure. In resources/views/components/disclosure.blade.php, use <details> and <summary> tags. Add a unique ID to the details element and set open attribute conditionally. Inside, put a slot for the content.
  4. Create a modal component using dialog element. Run php artisan make:component Modal. The native <dialog> element provides focus trapping and escape key handling without JavaScript. You’ll use the show() and close() methods via a small script or by toggling the open attribute.
  5. Style the modal with CSS. Use ::backdrop pseudo-element for the overlay and ensure the dialog is centered. Add aria-labelledby pointing to the modal’s title ID for screen readers.
  6. Build a tab component with radio inputs. Create a Tabs component that uses hidden radio buttons and CSS sibling selectors to switch panels. This approach is fully keyboard accessible and requires no JavaScript at all. Each radio button gets a label that acts as the tab.
  7. Implement a tooltip using CSS only. Create a Tooltip component with a button that has aria-describedby pointing to a hidden span. On hover and focus, the span appears via CSS :hover and :focus-within selectors.
  8. Add form validation error messages. In your forms, use Blade’s @error directive to display errors. Wrap inputs with aria-describedby linking to the error message ID, and add aria-invalid when errors exist.
  9. Test with keyboard and screen reader. Navigate through your components using Tab, Enter, Space, and Escape keys. Use a screen reader like NVDA or VoiceOver to verify announcements and focus order.
  10. Run automated accessibility checks. Use Lighthouse in Chrome DevTools or the axe browser extension to catch common issues like missing labels, contrast problems, and ARIA misuse.

Common Mistakes

  • Using aria-hidden on focusable elements—this hides them from screen readers but still allows keyboard focus, causing confusion.
  • Forgetting to manage focus when opening a modal or dialog. Always move focus into the dialog and back to the trigger on close.
  • Using div with click handlers instead of native buttons or links, which breaks keyboard accessibility.
  • Not providing visible focus indicators. Remove default outlines only if you replace them with a clear custom style.
  • Overusing ARIA roles when native HTML elements already provide the semantics. For example, use <nav> instead of role="navigation".

Tips

  • Leverage Laravel’s anonymous components for simple markup-only components—they’re cleaner and faster to write.
  • Use @props to define default attributes and merge them with the component’s attributes for flexibility.
  • Always provide a visible label for every input. Placeholder text is not a substitute.
  • For dynamic content (like a modal that appears on click), consider adding a tiny bit of vanilla JavaScript only for toggling—it’s still not a framework.
  • Test with real users if possible. Automated tools miss about 30% of accessibility issues.
  • Keep your CSS organized—use BEM or utility classes to manage component-specific styles.

Troubleshooting

  • Component not rendering. Check that the component class name matches the Blade file name. Run php artisan view:clear to clear cached views.
  • Details element not toggling. Ensure you haven’t added a click handler that prevents default behavior. The native toggle should work unless overridden.
  • Modal not showing. Verify the open attribute is set correctly. If using the show() method, ensure you’ve included the script that calls it.
  • Radio tabs not switching. Check that the radio inputs share the same name attribute and that CSS selectors use :checked correctly. Also ensure the labels are associated via for attributes.
  • Screen reader not announcing dynamic changes. Add aria-live="polite" to the region that updates, like an error summary.
  • Focus trapped in modal when it shouldn’t be. If using the native dialog, the browser handles it. If not, you may need to add a small script to trap focus—but ensure it’s not interfering with other components.

Frequently Asked Questions

Do I really need no JavaScript at all?

Not necessarily. The goal is to avoid a JavaScript framework. You can use a few lines of vanilla JS for things like toggling a class or calling showModal(). The key is that accessibility is built into the HTML semantics, not dependent on JS.

Are native HTML elements always more accessible than custom ones?

Yes, in most cases. Native elements like details, dialog, and button have built-in keyboard support and screen reader announcements. Custom elements require you to replicate all that behavior manually.

How do I handle complex components like a date picker?

For complex widgets, consider using a well-tested library that works with minimal JS, or break it down into simpler pieces like a text input with a pattern and validation. If you must build custom, follow the WAI-ARIA Authoring Practices for the pattern.

Will these components work with Livewire or Alpine.js if I add them later?

Yes, they will. Since they rely on standard HTML and CSS, they integrate fine with those tools. Just ensure that any JS you add doesn’t remove or override the accessibility attributes.

How can I test keyboard navigation quickly?

Open your page and press Tab repeatedly to see the focus order. Use Shift+Tab to go backward. For modals, press Escape to close, and check that focus returns to the trigger.

What if my client insists on a JavaScript framework?

You can still use a framework like Vue or React, but the same accessibility principles apply. The techniques here are framework-agnostic, so you can transfer them to any frontend stack.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →