Aliases

Aliases allow you to pass data from one component to any child component within its tree without having to pass it down as props in each level.

Aliases follow the Provider/Consumer pattern used in React’s Context API. An alias must be provided by a component, then explicitly consumed by another to use it. Once consumed, the alias is available as $<alias-name> on the tag.

Providing

Components may provide an alias using the @provide decorator or the tag.provide() method.

@provide(aliasName: string, resolver?: (props, state, aliases) => any)

A tag decorator that provides an alias with the given name for the component it decorates. If a resolver function is not supplied, the state is returned by default.

Example

@provide('customTag')
@tag('custom-tag', require('/gb-docs/index.html'))
class CustomTag {
    // ...
}

The @provide decorator can also take a resolver function. The following will provide the component’s props instead of its state:

@provide('customTag', (props, state, aliases) => props)
@tag('custom-tag', require('/gb-docs/index.html'))
class CustomTag {
    // ...
}

tag.provide(aliasName: string, resolver?: (props, state, aliases) => any)

A method to provide an alias with the given name for the component. If a resolver function is not supplied, the state is returned by default. Use this method in your init() function.

Example

init() {
    tag.provide('customTag');
}

The provide() function can also take a resolver function. The following will provide the component’s props instead of its state:

init() {
    tag.provide('customTag', (props, state, aliases) => props);
}

Consuming

An alias in the component’s scope is not automatically made accessible in a component; the alias must be consumed first. Consuming an alias makes the alias available within the component. However, a consumed alias is not made accessible to child components, so the alias must be consumed by the child component to use it there.

After an alias has been consumed, it can be accessed through the $<alias-name> property on the tag.

@consume(name: string)

A tag decorator that makes the alias with the given name accessible within the component.

Example

To consume the customTag alias provided in the example for @provide:

@consume('customTag')
@tag('custom-child-tag', require('/gb-docs/index.html'))
class CustomChildTag {
  // the alias can now be accessed as this.$customTag inside the class
}

tag.consume(aliasName: string)

A method to consume the alias with the given name for the component.

Example

init() {
  tag.consume('customTag');
  // the alias can now be accessed as this.$customTag here
  // and at any point after this in the lifecycle
}

_consumes attribute

An attribute on a component’s HTML tag that takes a comma-separated list of aliases. This attribute makes the given aliases accessible inside the component and is not necessary for native HTML tags.

Example

<custom-tag>
  <custom-child-tag _consumes="customTag">{ $customTag.value }</custom-child-tag>
</custom-tag>

Recall that an alias is not automatically consumed by any child components.

<custom-tag>
  <!-- $customTag is not accessible directly under the providing component -->
  <custom-child-tag _consumes="customTag">
    <!-- $customTag is accessble outside of any tags -->
    <span><!-- $customTag is accessible in this HTML tag --></span>
    <gb-container>
      <!-- $customTag is not accessble in this custom component -->
    </gb-container>
    <gb-container _consumes="customTag">
      <!-- $customTag is accessble in this custom component that consumes the alias -->
    </gb-container>
  </custom-child-tag>
</custom-tag>

Migrating from Legacy Aliasing

A number of simple changes must be made to migrate from the legacy aliasing pattern to the provide/consume pattern.

Table of Equivalents

Legacy Aliases