Block Content

Sometimes, we may want to provide some default content if the user of a component hasn't provided a block. For instance, consider an error message dialog that has a default message in cases where we don't know what error occurred. We could show the default message using the (has-block) syntax in an ErrorDialog component.

<dialog>
  {{#if (has-block)}}
    {{yield}}
  {{else}}
    An unknown error occurred!
  {{/if}}
</dialog>

Now, if we use our ErrorDialog component without a block, we'll get the default message.

<ErrorDialog/>

<!-- rendered -->
<dialog>
  An unknown error occurred!
</dialog>

If we had a more detailed message, though, we could use the block to pass it to the dialog.

<ErrorDialog>
  <Icon type="no-internet" />
  <p>You are not connected to the internet!</p>
</ErrorDialog>

Blocks can also pass values back into the template, similar to a callback function in JavaScript. Consider for instance a simple BlogPost component.

<h1>{{@post.title}}</h1>
<h2>{{@post.author}}</h2>

{{@post.body}}

<!-- usage -->
<BlogPost @post={{@blogPost}} />

We may want to give the user the ability to put extra content before or after the post, such as an image or a profile. Since we don't know what the user wants to do with the body of the post, we can instead pass the body back to them.

<h1>{{@post.title}}</h1>
<h2>{{@post.author}}</h2>

{{yield @post.body}}

<!-- usage -->
<BlogPost @post={{@blogPost}} as |postBody|>
  <img alt="" role="presentation" src="./blog-logo.png">

  {{postBody}}

  <AuthorBio @author={{@blogPost.author}} />
</BlogPost>

We can yield back multiple values as well, separated by spaces.

{{yield @post.title @post.author @post.body }}

<!-- usage -->
<BlogPost @post={{@blogPost}} as |postTitle postAuthor postBody|>
  <img alt="" role="presentation" src="./blog-logo.png">

  {{postTitle}}

  {{postBody}}

  <AuthorBio @author={{postAuthor}} />
</BlogPost>

If you want to yield content to different spots in the same component, you can use named blocks. You just need to specify a name for the yielded block, like this:

{{yield to="somePlace"}}

You could also want to pass some values. This is the same process as the default yield, but you just have to pass to as the last argument. An example would be the popover:

<div class="popover">
  <div class="popover__trigger">
    {{yield this.isOpen to="trigger"}}
  </div>
  {{#if this.isOpen}}
    <div class="popover__content">
      {{yield to="content"}}
    </div>
  {{/if}}
</div>

Without named blocks, we would certainly have to pass components as args to the popover. But this is much more practical!

Here’s how we would call our named blocks as a consumer:

<Popover>
  <:trigger as |open|>
    <button type="button">Click to {{if open "close" "open"}}  the popover!</button>
  </:trigger>
  <:content>
     This is what is shown when I'm opened!
  </:content>
</Popover>

We know the state of the popover because we passed it as an argument to the yield. To access its value, use the block parameters at the named block scope. It will not be accessible at the Popover level, so if you want the value to be available for all the blocks, you will have to pass it for each of them.

Rendering the previous code example would give this as result:

<!-- rendered -->
<div class="popover">
  <div class="popover__trigger">
    <button type="button">Click to close the popover!</button>
  </div>
  <div class="popover__content">
    This is what is showed when I'm opened!
  </div>
</div>

Don't worry, you can also still use yield by itself, and mix it with named blocks. Let’s take a card example:

<div class="card">
  {{#if (has-block "title")}}
    <div class="card__title">
      {{yield to="title"}}
    </div>
  {{/if}}
  <div class="card__content">
    {{yield}}
  </div>
</div>

A yielded block without a name is called default. So to access it, it’s like any other named blocks.

<Card>
  <:title>
    <h3>It's nice to have me. Sometimes</h3>
  </:title>
  <:default>
    The card content will appear here!
  </:default>
</Card>

The title being optional when you create a card, you can use the (has-block) helper with the named block by adding its name as a first parameter. That means you could also create this card:

<Card>
  I don't want any title, and I only have a default content!
</Card>

As you are not using named blocks, you can simply yield the content you would like to add, which becomes the default yield block.