Skip to content

feat(view): add x-slot define attribute to declare slot ownership in nested components #2104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
iamdadmin wants to merge 4 commits into
base: 3.x
Choose a base branch
from
Open

feat(view): add x-slot define attribute to declare slot ownership in nested components #2104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1d11af7
feat(view): define slot
iamdadmin Apr 4, 2026
04f7a95
tests(view): define slot
iamdadmin Apr 4, 2026
6e7867c
docs(view): slot define attribute
iamdadmin Apr 4, 2026
901546a
docs(view): further detail and explanation of slot define attribute
iamdadmin Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/1-essentials/02-views.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -470,6 +470,64 @@ For instance, the snippet below implements a tab component that accepts any numb
</x-tabs>
```

### Define slot ownership in nested view components

You can use `<x-slot name="mySlot" />` interchangeably to both *define* a slot with optional default content, or to provide content to *populate* the slot. Tempest will consider the hierarchy of the components from the AST to automatically detect your intent, however in more complex, especially nested, view components this can result in unexpected behaviour.

To override this behaviour and manually control in which view component your slots are considered to be *defined*, you can use `<x-slot define="mySlot" />` syntax instead. This causes the slot to be registered against the view component in which the keyword 'define' is used, instead of where the `slot` itself appears in the AST.

#### Extendable view component example using `define`

Let us assume you have an `x-container` view component, which is a `<div>` with formatting to act as a flex container for responsive sizing. You use this component repeatedly across your project, and it's effectively a macro to open and close the `<div>`; it doesn't have any slots or do anything special itself otherwise, with only a default `<x-slot/>` to render whatever it is given.
```html x-container.view.php
<div class="w-full max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"><x-slot/></div>
```
Now, assume we have an `x-header` in which we wish to use the `x-container`. Our `x-header` wishes to place slots `left` and `right` inside it; `x-header` owns these slots and wishes to expose these slots at the callsite in case they need custom content. Using the `define` keyword tells Tempest to treat these slots as *defined* by `x-header` instead of as a *slot to fill* inside `x-container`. Using `name` here instead of `define` would mean that Tempest falls back to the AST, and treats them as if they are slots of `<x-container>`.
```html x-header.view.php
<header>
<x-slot name="top" />
<x-container>
<x-slot define="left"> <!-- define this slot as a slot of x-header, compiled and passed into x-container's default slot -->
<x-header-left />
</x-slot>
<div>
I am in the center
</div>
<x-slot define="right"> <!-- define this slot as a slot of x-header, compiled and passed into x-container's default slot -->
<x-header-right />
</x-slot>
</x-container>
<x-slot name="bottom" />
</header>
```
At the callsite, you still use the `name` attribute to define which slot you're placing content into:
```html callsite.view.php
<x-header>
<x-slot name="left">Some content I want to insert</x-slot>
</x-header>
```
This example would replace the default content `<x-header-left />` instead with the literal string `Some content I want to insert` - or whatever you provide.

#### Populating a child's name slot using `define`

You can also push content into a child's named slot, not just the default slot, by creating a `define`d slot as follows:
```html x-outer.view.php
<div class="outer">
<x-inner>
<x-slot name="left">
<x-slot define="left">default-left-content</x-slot>
</x-slot>
</x-inner>
</div>
```
Again, the `define` keyword registers a `left` slot against the view component `<x-outer>` irrespective of it's position in the AST, and means that at the callsite:
```html outercallsite.view.php
<x-outer>
<x-slot name="left">My override</x-slot>
</x-outer>
```
And so, this places the literal string `My override` into `<x-innner>`'s `left` slot.

### Dynamic view components

On some occasions, you might want to dynamically render view components, for example, render a view component whose name is determined at runtime. You can use the `{html}<x-component :is="">` element to do so:
Expand Down
6 changes: 6 additions & 0 deletions packages/view/src/Elements/ViewComponentElement.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,12 @@ private function compileSlotToken(Token $slotToken): string

private function resolveSlotName(Token $slotToken): string
{
$define = $slotToken->getAttribute('define');

if ($define !== null && $define !== '') {
return $define;
}

$name = $slotToken->getAttribute('name');

if ($name !== null && $name !== '') {
Expand Down
135 changes: 135 additions & 0 deletions tests/Integration/View/ViewComponentTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1271,4 +1271,139 @@ public function test_nested_slot_rendering(): void

$this->assertSnippetsMatch($expected, $html);
}

public function test_define_slot_renders_default_content_into_child_component(): void
{
// <x-slot define="left"> in x-header's template is OWNED by x-header.
// x-container has no "left" slot — it only has a default slot.
// When the caller provides nothing for "left", the default content inside
// the define tag is compiled and flows into x-container's default slot.
$this->view->registerViewComponent('x-container', '<div class="container"><x-slot /></div>');
$this->view->registerViewComponent('x-header-left', '<span>default-left</span>');
$this->view->registerViewComponent('x-header', <<<'HTML'
<header>
<x-container>
<x-slot define="left">
<x-header-left />
</x-slot>
<div>center</div>
</x-container>
</header>
HTML);

$html = $this->view->render('<x-header></x-header>');

$this->assertSnippetsMatch(
'<header><div class="container"><span>default-left</span><div>center</div></div></header>',
$html,
);
}

public function test_define_slot_is_overridden_by_caller_using_name(): void
{
// When the caller fills the "left" slot using <x-slot name="left">, the compiled
// caller content replaces the default and flows into x-container's default slot.
// x-container remains unaware that "left" ever existed.
$this->view->registerViewComponent('x-container', '<div class="container"><x-slot /></div>');
$this->view->registerViewComponent('x-header-left', '<span>default-left</span>');
$this->view->registerViewComponent('x-header', <<<'HTML'
<header>
<x-container>
<x-slot define="left">
<x-header-left />
</x-slot>
<div>center</div>
</x-container>
</header>
HTML);

$html = $this->view->render(<<<'HTML'
<x-header>
<x-slot name="left"><span>custom-left</span></x-slot>
</x-header>
HTML);

$this->assertSnippetsMatch(
'<header><div class="container"><span>custom-left</span><div>center</div></div></header>',
$html,
);
}

public function test_multiple_define_slots_alongside_static_content_in_child_component(): void
{
// The full x-header scenario: two define slots flanking static content,
// all flowing as one contiguous default slot into x-container.
$this->view->registerViewComponent('x-container', '<div class="container"><x-slot /></div>');
$this->view->registerViewComponent('x-header-left', '<span>default-left</span>');
$this->view->registerViewComponent('x-header-right', '<span>default-right</span>');
$this->view->registerViewComponent('x-header', <<<'HTML'
<header>
<x-container>
<x-slot define="left"><x-header-left /></x-slot>
<div>center</div>
<x-slot define="right"><x-header-right /></x-slot>
</x-container>
</header>
HTML);

// No caller overrides — all three pieces use defaults.
$html = $this->view->render('<x-header></x-header>');

$this->assertSnippetsMatch(
'<header><div class="container"><span>default-left</span><div>center</div><span>default-right</span></div></header>',
$html,
);

// Caller overrides only "right"; "left" stays default.
$html = $this->view->render(<<<'HTML'
<x-header>
<x-slot name="right"><span>custom-right</span></x-slot>
</x-header>
HTML);

$this->assertSnippetsMatch(
'<header><div class="container"><span>default-left</span><div>center</div><span>custom-right</span></div></header>',
$html,
);
}

public function test_define_slot_inside_child_named_slot_filler(): void
{
// <x-slot define="left"> nested inside <x-slot name="left"> (a named slot filler
// for x-inner) evaluates x-outer's own "left" slot and places the result into
// x-inner's "left" slot. The parent of the define token is the x-slot filler tag,
// which is not a view component, so $parentIsComponent is false and compileSlotToken()
// is called correctly.
$this->view->registerViewComponent('x-inner', '<div class="inner"><x-slot name="left" /></div>');
$this->view->registerViewComponent('x-header-left', '<span>default-left</span>');
$this->view->registerViewComponent('x-outer', <<<'HTML'
<div class="outer">
<x-inner>
<x-slot name="left">
<x-slot define="left"><x-header-left /></x-slot>
</x-slot>
</x-inner>
</div>
HTML);

// No caller override — default content flows through into x-inner's named slot.
$html = $this->view->render('<x-outer></x-outer>');

$this->assertSnippetsMatch(
'<div class="outer"><div class="inner"><span>default-left</span></div></div>',
$html,
);

// Caller overrides "left" — custom content flows through into x-inner's named slot.
$html = $this->view->render(<<<'HTML'
<x-outer>
<x-slot name="left"><span>custom-left</span></x-slot>
</x-outer>
HTML);

$this->assertSnippetsMatch(
'<div class="outer"><div class="inner"><span>custom-left</span></div></div>',
$html,
);
}
}
Loading