smnandre/symfony-ux-skills / skills/live-component
live-component
VerifiedSymfony UX LiveComponent for reactive server-rendered UI -- components that re-render via AJAX on user interaction, zero JavaScript required. Use when building live search, real-time filtering, dynamic forms, inline validation, dependent selects, auto-save, polling, deferred/lazy rendering, or any UI that updates itself based on user input. Code triggers: AsLiveComponent, LiveProp, LiveAction, data-model, data-loading, data-live-action-url, ComponentWithFormTrait, LiveListener, emit, defer, lazy, polling. Also trigger when the user asks "how to build a search that filters as I type", "how to validate a form in real-time", "how to make a reactive component in PHP", "how to build dependent selects", "how to defer component rendering", "how to communicate between components via emit", "how to bind a form to a LiveComponent". Do NOT trigger for static reusable UI without reactivity (use twig-component), pure client-side JS behavior (use stimulus), or page-level navigation (use turbo).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
| references/api.md | markdown | 10.2 KB |
| references/gotchas.md | markdown | 7.9 KB |
| references/patterns.md | markdown | 15.3 KB |
references/gotchas.md
View on GitHub# LiveComponent Gotchas & Debugging
Common pitfalls and solutions.
---
## Props Not Persisting
### Non-LiveProp Values Reset
```php
// ❌ Regular property - resets on every re-render
public string $query = '';
// ✅ LiveProp - persists between re-renders
#[LiveProp]
public string $query = '';
```
### Props Must Be Writable for data-model
```php
// ❌ Not writable - data-model won't work
#[LiveProp]
public string $search = '';
// ✅ Writable - data-model works
#[LiveProp(writable: true)]
public string $search = '';
```
### Object Props Need Hydration
```php
// ❌ Complex objects can't auto-hydrate
#[LiveProp]
public ComplexDTO $data;
// ✅ Entity with ID - auto-hydrates
#[LiveProp]
public Product $product;
// ✅ Custom hydration for DTOs
#[LiveProp(hydrateWith: 'hydrateData', dehydrateWith: 'dehydrateData')]
public ComplexDTO $data;
```
---
## Missing DefaultActionTrait
```php
// ❌ Won't work - missing trait
#[AsLiveComponent]
final class MyComponent
{
}
// ✅ Must include DefaultActionTrait
#[AsLiveComponent]
final class MyComponent
{
use DefaultActionTrait;
}
```
---
## Missing attributes in Template
```twig
{# ❌ Component won't work - missing attributes #}
<div>
Content
</div>
{# ✅ Root element must have {{ attributes }} #}
<div {{ attributes }}>
Content
</div>
```
---
## data-model Binding Issues
### Wrong Element for Binding
```twig
{# ❌ data-model on non-input element #}
<div data-model="query">...</div>
{# ✅ data-model on input/select/textarea #}
<input data-model="query">
<select data-model="category">
<textarea data-model="content">
```
### Nested Property Access
```php
#[LiveProp(writable: ['email', 'name'])]
public User $user;
```
```twig
{# ✅ Access nested properties #}
<input data-model="user.email">
<input data-model="user.name">
{# ❌ Property not in writable list #}
<input data-model="user.password">
```
### Checkbox/Radio Binding
```twig
{# Checkbox needs value or boolean prop #}
<input type="checkbox" data-model="enabled">
{# Multiple checkboxes to array #}
<input type="checkbox" data-model="selectedIds" value="1">
<input type="checkbox" data-model="selectedIds" value="2">
```
---
## Action Errors
### Action Not Found
```php
// ❌ Missing LiveAction attribute
public function save(): void { }
// ✅ Must have LiveAction attribute
#[LiveAction]
public function save(): void { }
```
### Wrong Parameter Name
```twig
{# Template #}
<button
data-action="live#action"
data-live-action-param="delete"
data-live-id-param="{{ id }}" {# param name: id #}
>
```
```php
// ❌ Param name mismatch
#[LiveAction]
public function delete(#[LiveArg] int $itemId): void { }
// ✅ Matching param name
#[LiveAction]
public function delete(#[LiveArg] int $id): void { }
// ✅ Or specify custom name
#[LiveAction]
public function delete(#[LiveArg('id')] int $itemId): void { }
```
---
## Form Issues
### Form Not Validating
```php
// ❌ Form not submitted
#[LiveAction]
public function save(): void
{
$data = $this->getForm()->getData(); // Not validated!
}
// ✅ Submit form first
#[LiveAction]
public function save(): void
{
$this->submitForm(); // Validates
if (!$this->getForm()->isValid()) {
return; // Re-renders with errors
}
$data = $this->getForm()->getData();
}
```
### initialFormData Type Mismatch
```php
// ❌ Wrong type for initialFormData
#[LiveProp]
public ?array $initialFormData = null;
// ✅ Match form's data_class
#[LiveProp]
public ?User $initialFormData = null;
```
### Form Re-creation Issues
```php
protected function instantiateForm(): FormInterface
{
// ❌ Creating form with data from prop that changes
return $this->createForm(UserType::class, $this->user);
// ✅ Use initialFormData for initial state
return $this->createForm(UserType::class, $this->initialFormData);
}
```
---
## Hydration Errors
### Entity Not Found
```php
#[LiveProp]
public Product $product; // ❌ If product deleted, hydration fails
```
Solution: Make nullable or handle in mount:
```php
#[LiveProp]
public ?Product $product = null;
public function mount(?Product $product): void
{
$this->product = $product;
}
```
### Collection Hydration
```php
// ❌ Array of entities won't auto-hydrate
#[LiveProp]
public array $products = [];
// ✅ Store IDs and fetch in getter
#[LiveProp]
public array $productIds = [];
public function getProducts(): array
{
return $this->productRepository->findBy(['id' => $this->productIds]);
}
```
---
## Performance Issues
### Too Many Re-renders
```twig
{# ❌ Re-renders on every keystroke #}
<input data-model="search">
{# ✅ Debounce to reduce requests #}
<input data-model="debounce(300)|search">
{# ✅ Only update on blur #}
<input data-model="on(blur)|search">
```
### Heavy Computed Properties
```php
// ❌ Expensive query on every render
public function getProducts(): array
{
return $this->repository->findWithComplexQuery();
}
// ✅ Use computed caching
```
```twig
{# Computed is cached within single render #}
{% for product in computed.products %}
```
### Large DOM Updates
```twig
{# ❌ Large list without stable IDs #}
{% for item in items %}
<div>{{ item.name }}</div>
{% endfor %}
{# ✅ Add data-live-id for efficient morphing #}
{% for item in items %}
<div data-live-id="{{ item.id }}">{{ item.name }}</div>
{% endfor %}
```
---
## DOM Preservation
### Third-Party Widgets Destroyed
```twig
{# ❌ Widget re-initialized on every render #}
<select class="select2">
{# ✅ Prevent morphing #}
<div data-live-ignore>
<select class="select2">
</div>
```
### User Input Lost
```twig
{# ❌ Input value reset during morph #}
<input type="text" name="temp">
{# ✅ Preserve specific attribute #}
<input type="text" name="temp" data-live-preserve="value">
```
---
## Event Issues
### Event Not Received
```php
// Child emits
$this->emit('item:saved', ['id' => 1]);
// ❌ Parent listener method name mismatch
#[LiveListener('itemSaved')] // Wrong event name
public function onItemSaved(): void { }
// ✅ Exact event name match
#[LiveListener('item:saved')]
public function onItemSaved(#[LiveArg] int $id): void { }
```
### emitUp vs emit
```php
// emit - broadcasts to all listeners
$this->emit('event');
// emitUp - only to parent components
$this->emitUp('event');
// emitTo - to specific component
$this->emitTo('ComponentName', 'event');
```
---
## URL Sync Issues
### URL Not Updating
```php
// ❌ Missing writable
#[LiveProp(url: true)]
public string $query = '';
// ✅ Must be writable for URL sync
#[LiveProp(writable: true, url: true)]
public string $query = '';
```
### History State
```php
// Default: replaces URL without history entry
#[LiveProp(writable: true, url: true)]
// Push to history (back button works)
use Symfony\UX\LiveComponent\Metadata\UrlMapping;
#[LiveProp(writable: true, url: new UrlMapping(history: 'push'))]
```
---
## Debugging
### Enable Debug Mode
Check browser console for LiveComponent logs.
### Inspect Component State
```twig
{# Debug: show current state #}
<pre>{{ _context|json_encode(constant('JSON_PRETTY_PRINT')) }}</pre>
```
### Network Tab
1. Open DevTools → Network
2. Filter by Fetch/XHR
3. Look for requests to `/_components/`
4. Check request payload for props
5. Check response for HTML
### Common Errors
| Error | Cause |
|-------|-------|
| "Component not found" | Missing `#[AsLiveComponent]` or not in configured namespace |
| "Checksum mismatch" | LiveProp changed without being writable |
| "Cannot hydrate" | Entity deleted or custom type without hydrator |
| "Action not found" | Missing `#[LiveAction]` attribute |
### Test in Isolation
```php
use Symfony\UX\LiveComponent\Test\InteractsWithLiveComponents;
public function testComponent(): void
{
$component = $this->createLiveComponent('MyComponent', [
'initialProp' => 'value'
]);
// Debug
dump($component->render());
dump($component->get('propName'));
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |