NovaCard HTML

Any HTML you can render in PHP, as a Laravel Nova card — a string, a Markdown document or a Blade view, placed on the dashboard grid, lazy-loaded so it never blocks the paint.

📖 Read the documentation →

Every method, every config key, a card-geometry sheet you can drive yourself, and a live specimen where every presentation and behaviour option rewrites the call as you click it.

[!CAUTION] Upgrading from 2.x? Read UPGRADE.md first. The default height is now dynamic and the default alignment is left. Your content() methods are untouched; php artisan nova-card-html:upgrade --dry-run previews the rest.

[!IMPORTANT] A ⭐ costs you nothing and helps other developers find this package. Sponsoring keeps it compatible with every new Laravel and Nova release.

What it does

Nova ships metrics. If you want a number, a trend or a breakdown, use Value, Trend or Partition — they cache, they range-select, and you write no markup at all. If you want a widget with its own state, forms and events, write a real Vue card; you will end up there anyway.

This package is the middle: markup your application already produces, on the dashboard grid, without a build step.

• Four content sources — a string, Markdown, a Blade view, or escaped text.
• Lazy loading that keeps card queries off the dashboard's critical path, with #[LazyState] to carry a selected year or filter across the fetch.
• Response caching and polling, keyed on the card class and its state.
• Dark mode, five accent themes, card-scoped CSS — and pixel heights applied inline, so they work whatever your Tailwind build generated.
• An opt-in sanitizer for the content you did not author.
• 4.95 kB of JavaScript and 2.23 kB of CSS, both gzipped under 2 kB, with no runtime dependency of its own.

Card content is a trust boundary: this renders server-produced HTML through Vue's v-html, and the package cannot tell your markup from a user's name that ended up inside it. That is what sanitize() and text() are for.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• Nova 5.7+ — Nova 6 is explicitly conflicted

Installation

composer require gabrielesbaiz/nova-card-html

php artisan nova-card-html MyHtmlCard

php artisan vendor:publish --tag=nova-card-html-config
php artisan vendor:publish --tag=nova-card-html-lang

The service provider is auto-discovered and the assets register themselves with Nova: no migrations, no tables, nothing to add to NovaServiceProvider. Both publish steps are optional — the card works untouched.

Full installation guide →

Artisan commands

| Command | Purpose | |---|---| | nova-card-html {name} | Generate a card in app/Nova/Cards. --force overwrites. | | nova-card-html:upgrade | Migrate 2.x subclasses to the 3.0 defaults, and report what is a candidate for the new features. --dry-run writes nothing. |

See the commands page.

Documentation

| | | |---|---| | Documentation site | Everything: install, configure, operate. | | Guide | Building a card, and the four content sources. | | Performance | Caching, lazy loading, #[LazyState], polling. | | API reference | All thirty-two methods, with defaults. | | Configuration | All sixteen keys, and what changing them does. | | Security | The trust boundary, and what is deliberate. | | UPGRADE.md | Upgrading from 2.x. Read before you start. | | CHANGELOG.md | What changed, and when. |

Testing

composer test        # Pest
composer analyse     # PHPStan
composer format      # Pint
npm run test         # Vitest, for the Vue component
npm run build        # rebuild dist/

There is no CI. Those commands are the contract. dist/ is committed because the service provider serves from it, so any change under resources/ ships with a rebuilt bundle.

Contributing

Thank you for considering contributing. The guide is in CONTRIBUTING.md.

Security vulnerabilities

Please review SECURITY.md for reporting a vulnerability. Please do not open a public issue.

Credits

Written and maintained by Gabriele Sbaiz.

Originally based on abordage/nova-card-html by Pavel Bychko. It builds on Laravel and Laravel Nova, and optionally on league/commonmark and mews/purifier.

Support this package

If it is useful to you:

• ⭐ Star the repo. Free, thirty seconds, and it is the first signal other developers look at.
• ❤️ Become a sponsor. From $5 a month.
• 🐛 Open a good issue. A clear reproduction is worth more than you think.
• 🗣️ Tell another Laravel developer. Word of mouth is how packages survive.

Disclaimer

This package is provided as is, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, title and non-infringement. To the fullest extent permitted by applicable law, in no event shall the authors, copyright holders or contributors be liable for any claim, damages or other liability — whether in an action of contract, tort or otherwise — arising from, out of or in connection with this package or its use, including without limitation any direct, indirect, incidental, special, exemplary, consequential or punitive damages, loss of data, loss of profits, business interruption, account compromise, or unauthorised access.

This package renders HTML that your application produces, through v-html, without inspecting it by default. Whoever deploys it is responsible for deciding whether a given card's content is safe to render unescaped. That responsibility includes, and is not limited to, calling sanitize() or text() on anything a user can influence, reviewing what your own content() methods interpolate, restricting who can see a card with canSee() or authorize(), and reviewing the code yourself before putting it in front of data you cannot afford to leak. Nothing here constitutes security, legal or compliance advice.

Use of this package is entirely at your own risk.

License

MIT. See LICENSE.md. The MIT licence's warranty disclaimer and limitation of liability apply in full, alongside the disclaimer above.