Template tags¤

All following template tags are defined in

django_components.templatetags.component_tags

Import as

{% load component_tags %}

component_css_dependencies¤

{% component_css_dependencies  %}

See source code

Marks location where CSS link tags should be rendered after the whole HTML has been generated.

Generally, this should be inserted into the <head> tag of the HTML.

If the generated HTML does NOT contain any {% component_css_dependencies %} tags, CSS links are by default inserted into the <head> tag of the HTML. (See Default JS / CSS locations)

Note that there should be only one {% component_css_dependencies %} for the whole HTML document. If you insert this tag multiple times, ALL CSS links will be duplicately inserted into ALL these places.

component_js_dependencies¤

{% component_js_dependencies  %}

See source code

Marks location where JS link tags should be rendered after the whole HTML has been generated.

Generally, this should be inserted at the end of the <body> tag of the HTML.

If the generated HTML does NOT contain any {% component_js_dependencies %} tags, JS scripts are by default inserted at the end of the <body> tag of the HTML. (See Default JS / CSS locations)

Note that there should be only one {% component_js_dependencies %} for the whole HTML document. If you insert this tag multiple times, ALL JS scripts will be duplicately inserted into ALL these places.

component¤

{% component *args: Any, **kwargs: Any [only] %}
{% endcomponent %}

See source code

Renders one of the components that was previously registered with @register() decorator.

The {% component %} tag takes:

Component's registered name as the first positional argument,
Followed by any number of positional and keyword arguments.

{% load component_tags %}
<div>
    {% component "button" name="John" job="Developer" / %}
</div>

The component name must be a string literal.

Inserting slot fills¤

If the component defined any slots, you can "fill" these slots by placing the {% fill %} tags within the {% component %} tag:

{% component "my_table" rows=rows headers=headers %}
  {% fill "pagination" %}
    < 1 | 2 | 3 >
  {% endfill %}
{% endcomponent %}

You can even nest {% fill %} tags within {% if %}, {% for %} and other tags:

{% component "my_table" rows=rows headers=headers %}
    {% if rows %}
        {% fill "pagination" %}
            < 1 | 2 | 3 >
        {% endfill %}
    {% endif %}
{% endcomponent %}

Isolating components¤

By default, components behave similarly to Django's {% include %}, and the template inside the component has access to the variables defined in the outer template.

You can selectively isolate a component, using the only flag, so that the inner template can access only the data that was explicitly passed to it:

{% component "name" positional_arg keyword_arg=value ... only %}

Alternatively, you can set all components to be isolated by default, by setting context_behavior to "isolated" in your settings:

# settings.py
COMPONENTS = {
    "context_behavior": "isolated",
}

Omitting the component keyword¤

If you would like to omit the component keyword, and simply refer to your components by their registered names:

{% button name="John" job="Developer" / %}

You can do so by setting the "shorthand" Tag formatter in the settings:

# settings.py
COMPONENTS = {
    "tag_formatter": "django_components.component_shorthand_formatter",
}

fill¤

{% fill name: str, *, data: Optional[str] = None, fallback: Optional[str] = None, body: Union[str, django.utils.safestring.SafeString, django_components.slots.SlotFunc[~TSlotData], django_components.slots.Slot[~TSlotData], NoneType] = None, default: Optional[str] = None %}
{% endfill %}

See source code

Use {% fill %} tag to insert content into component's slots.

{% fill %} tag may be used only within a {% component %}..{% endcomponent %} block, and raises a TemplateSyntaxError if used outside of a component.

Args:

name (str, required): Name of the slot to insert this content into. Use "default" for the default slot.
data (str, optional): This argument allows you to access the data passed to the slot under the specified variable name. See Slot data.
fallback (str, optional): This argument allows you to access the original content of the slot under the specified variable name. See Slot fallback.

Example:

{% component "my_table" %}
  {% fill "pagination" %}
    < 1 | 2 | 3 >
  {% endfill %}
{% endcomponent %}

Access slot fallback¤

Use the fallback kwarg to access the original content of the slot.

The fallback kwarg defines the name of the variable that will contain the slot's fallback content.

Access slot data¤

Use the data kwarg to access the data passed to the slot.

The data kwarg defines the name of the variable that will contain the slot's data.

Using default slot¤

To access slot data and the fallback slot content on the default slot, use {% fill %} with name set to "default":

{% component "button" %}
  {% fill name="default" data="slot_data" fallback="slot_fallback" %}
    You clicked me {{ slot_data.count }} times!
    {{ slot_fallback }}
  {% endfill %}
{% endcomponent %}

Slot fills from Python¤

You can pass a slot fill from Python to a component by setting the body kwarg on the {% fill %} tag.

First pass a Slot instance to the template with the get_template_data() method:

from django_components import component, Slot

class Table(Component):
  def get_template_data(self, args, kwargs, slots, context):
    return {
        "my_slot": Slot(lambda ctx: "Hello, world!"),
    }

Then pass the slot to the {% fill %} tag:

{% component "table" %}
  {% fill "pagination" body=my_slot / %}
{% endcomponent %}

Warning

If you define both the body kwarg and the {% fill %} tag's body, an error will be raised.

{% component "table" %}
  {% fill "pagination" body=my_slot %}
    ...
  {% endfill %}
{% endcomponent %}

html_attrs¤

{% html_attrs attrs: Optional[Dict] = None, defaults: Optional[Dict] = None, **kwargs: Any %}

See source code

Generate HTML attributes (key="value"), combining data from multiple sources, whether its template variables or static text.

It is designed to easily merge HTML attributes passed from outside as well as inside the component.

Args:

attrs (dict, optional): Optional dictionary that holds HTML attributes. On conflict, overrides values in the default dictionary.
default (str, optional): Optional dictionary that holds HTML attributes. On conflict, is overriden with values in the attrs dictionary.
Any extra kwargs will be appended to the corresponding keys

The attributes in attrs and defaults are merged and resulting dict is rendered as HTML attributes (key="value").

Extra kwargs (key=value) are concatenated to existing keys. So if we have

attrs = {"class": "my-class"}

Then

{% html_attrs attrs class="extra-class" %}

will result in class="my-class extra-class".

Example:

<div {% html_attrs
    attrs
    defaults:class="default-class"
    class="extra-class"
    data-id="123"
%}>

renders

<div class="my-class extra-class" data-id="123">

See more usage examples in HTML attributes.

provide¤

{% provide name: str, **kwargs: Any %}
{% endprovide %}

See source code

The {% provide %} tag is part of the "provider" part of the provide / inject feature.

Pass kwargs to this tag to define the provider's data.

Any components defined within the {% provide %}..{% endprovide %} tags will be able to access this data with Component.inject().

This is similar to React's ContextProvider, or Vue's provide().

Args:

name (str, required): Provider name. This is the name you will then use in Component.inject().
**kwargs: Any extra kwargs will be passed as the provided data.

Example:

Provide the "user_data" in parent component:

@register("parent")
class Parent(Component):
    template = """
      <div>
        {% provide "user_data" user=user %}
          {% component "child" / %}
        {% endprovide %}
      </div>
    """

    def get_template_data(self, args, kwargs, slots, context):
        return {
            "user": kwargs["user"],
        }

Since the "child" component is used within the {% provide %} / {% endprovide %} tags, we can request the "user_data" using Component.inject("user_data"):

@register("child")
class Child(Component):
    template = """
      <div>
        User is: {{ user }}
      </div>
    """

    def get_template_data(self, args, kwargs, slots, context):
        user = self.inject("user_data").user
        return {
            "user": user,
        }

Notice that the keys defined on the {% provide %} tag are then accessed as attributes when accessing them with Component.inject().

✅ Do this

user = self.inject("user_data").user

❌ Don't do this

user = self.inject("user_data")["user"]

slot¤

{% slot name: str, **kwargs: Any [default] [required] %}
{% endslot %}

See source code

{% slot %} tag marks a place inside a component where content can be inserted from outside.

Learn more about using slots.

This is similar to slots as seen in Web components, Vue or React's children.

Args:

name (str, required): Registered name of the component to render
default: Optional flag. If there is a default slot, you can pass the component slot content without using the {% fill %} tag. See Default slot
required: Optional flag. Will raise an error if a slot is required but not given.
**kwargs: Any extra kwargs will be passed as the slot data.

Example:

@register("child")
class Child(Component):
    template = """
      <div>
        {% slot "content" default %}
          This is shown if not overriden!
        {% endslot %}
      </div>
      <aside>
        {% slot "sidebar" required / %}
      </aside>
    """

@register("parent")
class Parent(Component):
    template = """
      <div>
        {% component "child" %}
          {% fill "content" %}
            🗞️📰
          {% endfill %}

          {% fill "sidebar" %}
            🍷🧉🍾
          {% endfill %}
        {% endcomponent %}
      </div>
    """

Slot data¤

Any extra kwargs will be considered as slot data, and will be accessible in the {% fill %} tag via fill's data kwarg:

Slot fallback¤

The content between the {% slot %}..{% endslot %} tags is the fallback content that will be rendered if no fill is given for the slot.

This fallback content can then be accessed from within the {% fill %} tag using the fill's fallback kwarg. This is useful if you need to wrap / prepend / append the original slot's content.

@register("child")
class Child(Component):
    template = """
      <div>
        {% slot "content" %}
          This is fallback content!
        {% endslot %}
      </div>
    """

@register("parent")
class Parent(Component):
    template = """
      {# Parent can access the slot's fallback content #}
      {% component "child" %}
        {% fill "content" fallback="fallback" %}
          {{ fallback }}
        {% endfill %}
      {% endcomponent %}
    """