Authoring Custom Blade Components
WireKit components are plain Blade anonymous components — no special
build step, no class hierarchy to inherit from. You write your own
custom components alongside WireKit's, mix-and-match in your views, and
the WireKit tooling (wirekit:show, wirekit:export-json,
wirekit:doctor) introspects them through the same machinery it uses
for the shipped catalog.
This page documents the @props([...]) syntax shapes WireKit's
toolchain understands. Following the patterns here ensures your custom
components show up correctly in wirekit:show and in AI-tool
autocomplete.
The Minimum Viable Component
{{-- resources/views/components/my-button.blade.php --}}
@props([
'intent' => 'primary',
'size' => 'md',
])
<button {{ $attributes->class([
'rounded px-3 py-1.5',
'bg-[var(--color-wk-accent)] text-[color:var(--color-wk-accent-fg)]' => $intent === 'primary',
'bg-[var(--color-wk-bg-muted)] text-[color:var(--color-wk-text)]' => $intent === 'neutral',
'text-sm' => $size === 'sm',
'text-base' => $size === 'md',
]) }}>
{{ $slot }}
</button>
Use it from any Blade view:
<x-my-button>Save</x-my-button>
<x-my-button intent="neutral" size="sm">Cancel</x-my-button>
WireKit's tooling immediately recognizes the props:
php artisan tinker --execute='
use Pushery\WireKit\Support\PropsParser;
dd(PropsParser::parseBlade(resource_path("views/components/my-button.blade.php")));
'
…returns the two prop entries with their defaults.
@props Shape Reference
The parser handles the following expressions inside an @props([...])
block. If your default expression doesn't fit one of these shapes, the
parser may still handle it — but these are the shapes it is tested
against.
1 · Bare literals
@props([
'count' => 0,
'enabled' => true,
'tag' => 'div',
'maxRows' => null,
])
Primitive types — integers, booleans, strings, null. Always works.
2 · config(...) defaults with commas in arguments
@props([
'variant' => config('myapp.components.button.variant', 'primary'),
])
The parser recognizes commas inside the config(...) argument list as
part of the default expression, not as prop boundaries.
3 · Trailing inline // comment
@props([
'trend' => null, // 'up' | 'down' | 'neutral' | null
])
The comment is captured as a separate comment field on the prop
record (not as part of the default value). wirekit:show <name>
prints the comment in gray alongside the prop name, making the
allowed-value enumeration discoverable without opening the source file.
4 · match(...) expressions
@props([
'classes' => match (1) {
1 => 'text-4xl',
2 => 'text-3xl',
default => 'text-base',
},
])
Useful for deriving the default from another prop at render time.
5 · Array-literal defaults
@props([
'items' => [1, 2, 3],
'config' => ['enabled' => true, 'limit' => 10],
])
Both flat and nested arrays parse cleanly. Use heredoc syntax (below) for very long inline arrays — readability beats brevity.
6 · Mixed single- and double-quoted keys
@props([
'variant' => 'outline',
"size" => "md",
])
Both quote styles are valid PHP. The parser strips them uniformly when extracting the prop name.
7 · Multi-line default expressions
@props([
'classes' => implode(' ', [
'flex',
'items-center',
'gap-2',
]),
])
The parser tracks bracket / paren nesting via PHP's tokenizer, so multi-line expressions don't trip it up. Indent for readability.
8 · Heredoc / nowdoc defaults
@props([
'template' => <<<'TEMPLATE'
<div>
Hello, world.
</div>
TEMPLATE,
])
Useful for long inline strings that contain special characters
(backticks, double quotes, </script> sequences).
What the Parser Returns
use Pushery\WireKit\Support\PropsParser;
$props = PropsParser::parseBlade('resources/views/components/my-button.blade.php');
Each entry in the returned list has the same shape:
[
'name' => 'intent',
'default' => "'primary'", // Raw source text.
'default_normalized' => "'primary'", // Whitespace-collapsed.
'type_hint' => null, // A @props block declares no types.
'comment' => null, // Or "'up' | 'down'" etc.
'examples' => [], // Values the prop's own `@example` tags name.
'values' => ['primary', 'accent'], // What validateProp() accepts, or null.
'value_type' => 'string', // bool | int | float | string | array, or null.
]
The same data drives wirekit:show <name>, wirekit:show <name> --as=json,
and wirekit:export-json.
CLI Tooling for Custom Components
Once your component is in resources/, every WireKit
CLI command sees it:
# Programmatic introspection — same JSON shape as shipped components
php artisan wirekit:show my-button --as=json
# Lint a developer Blade file against your component's prop set
php artisan wirekit:show my-button --validate-against=resources/views/pages/checkout.blade.php
Note: wirekit:list and the registry-based commands only list
components that are in Pushery\. Custom
components in resources/ are visible to
wirekit:show (which file-walks) but not to wirekit:list (which
reads the registry). If you want your custom component to show up in
the registry, register it via your service provider — but the typical
pattern is "custom components stay local, only WireKit's catalog
lives in the registry".
A Conditional Block at the End of an Element
Inside a Livewire component, Livewire wraps every @if, @unless,
@foreach and the other block directives in two HTML comments:
<!--[if BLOCK]><![endif]--> before the block and
<!--[if ENDBLOCK]><![endif]--> after it. When the component updates,
Livewire's DOM morph reads them, so a block that appears or disappears
does not pair the elements after it with the wrong ones.
A block with nothing after it in its parent element has no such
elements. @wirekitLast is @if without the two comments. It takes the
same condition and the same @elseif and @else branches, and it
closes with @endwirekitLast:
{{-- resources/views/components/member-row.blade.php --}}
@props(['name', 'verified' => false])
<div class="flex items-center gap-2">
{{-- 1. The name always renders. --}}
<span>{{ $name }}</span>
{{-- 2. The last child of the div: nothing follows it inside the div. --}}
@wirekitLast($verified)
<x-wirekit::badge>Verified</x-wirekit::badge>
@else
<span class="text-sm">Not verified yet</span>
@endwirekitLast
</div>
Outside a Livewire component, Livewire writes no comments, and
@wirekitLast renders exactly as @if does. Inside one, each such
block leaves out two comments on every render.
Use it only where all three conditions hold, and write @if everywhere
else:
- The closing tag of an HTML element follows
@endwirekitLastdirectly, as</div>does above. An echo such as{{ $slot }}, another block or another element after it rules the block out, and so does the closing tag of a component or a slot (</x-…>), because the component can place that content before other elements. - Each branch closes every tag it opens.
- The block does not stand inside a
<template>element.
Common Pitfalls
Variable / expression as the array key
// Don't do this. PHP allows it but `@props` doesn't.
@props([
$dynamicKey => 'value', // ← parser can't extract a string name
])
@props array keys must be string literals. The parser silently skips
non-string-literal keys. If wirekit:show <name> prints a truncated
default or a prop you did not write, file a bug with the @props block.
Asserting strict-mode warnings in tests
When app.debug is true (or you run in the console), WireKit emits a
warning-level log for an unknown prop key passed to a component — a
Did-you-mean signal that a typo'd prop (<x-wirekit::) was
silently dropped into the attribute bag. It is logged through the strictness
gate and never throws.
To assert that warning in a test you need it to (a) not land in
storage/ — otherwise the wirekit:verify silent-typo
log-scan would later report it as a finding — and (b) stay type-clean under
static analysis (Larastan). Two common reaches don't fit:
Log::fake()— Laravel has no such method (unlikeEvent::fake()/Queue::fake()); calling it errors withundefined method …::fake().Log::— a Mockery facade expectation, which Larastan flags at higher levels on the dynamically-typed return.should Receive(…)
Swap the logger for a tiny array recorder instead — it replaces the channel entirely (nothing reaches the file handler) and uses only typed PSR-3 methods, so it is both log-scan-safe and Larastan-clean:
use Illuminate\Support\Facades\Log;
use Pushery\WireKit\WireKit;
use Psr\Log\AbstractLogger;
it('warns on an unknown prop key in debug mode', function () {
// 1. Strict-mode warnings only emit when app.debug is on.
config()->set('app.debug', true);
// 2. Replace the logger with an array recorder — no disk write, no Mockery.
$records = [];
Log::swap(new class($records) extends AbstractLogger {
public function __construct(private array &$records) {}
public function log($level, string|\Stringable $message, array $context = []): void
{
$this->records[] = [(string) $level, (string) $message];
}
});
// 3. Drive the unknown-prop path. WireKit's components call this helper
// internally; in a focused unit test you can call it directly with a key
// that isn't a declared prop (stable across releases, unlike a specific
// component's prop list).
WireKit::warnUnknownProps('button', ['surfce' => 'ghost'], ['intent', 'surface']);
// 4. Assert the warning fired — captured in memory, never written to disk.
expect($records)->toHaveCount(1)
->and($records[0][0])->toBe('warning')
->and($records[0][1])->toContain('Unknown prop "surfce"');
});
See Also
- ComponentRegistry — Programmatic Discovery — reading the catalog at runtime.
- Authoring Custom Alpine Plugins — defensive-cleanup pattern for plugins that drive your components.
- CLI Reference — full command surface.