API

tag: str

The tag name.

E.g. "component" or "slot" will make this class match template tags {% component %} or {% slot %}.

class SlotNode(BaseNode):
    tag = "slot"
    end_tag = "endslot"

This will allow the template tag {% slot %} to be used like this:

{% slot %} ... {% endslot %}

end_tag: str | None

The end tag name.

E.g. "endcomponent" or "endslot" will make this class match template tags {% endcomponent %} or {% endslot %}.

class SlotNode(BaseNode):
    tag = "slot"
    end_tag = "endslot"

This will allow the template tag {% slot %} to be used like this:

{% slot %} ... {% endslot %}

If not set, then this template tag has no end tag.

So instead of {% component %} ... {% endcomponent %}, you'd use only {% component %}.

class MyNode(BaseNode):
    tag = "mytag"
    end_tag = None

allowed_flags: Iterable[str] | None

The list of all possible flags for this tag.

E.g. ["required"] will allow this tag to be used like {% slot required %}.

class SlotNode(BaseNode):
    tag = "slot"
    end_tag = "endslot"
    allowed_flags = ["required", "default"]

This will allow the template tag {% slot %} to be used like this:

{% slot required %} ... {% endslot %}
{% slot default %} ... {% endslot %}
{% slot required default %} ... {% endslot %}

params: list[TagAttr]

The parameters to the tag in the template.

A single param represents an arg or kwarg of the template tag.

E.g. the following tag:

{% component "my_comp" key=val key2='val2 two' %}

Has 3 params:

• Posiitonal arg "my_comp"
• Keyword arg key=val
• Keyword arg key2='val2 two'

start_tag_source: str | None

The source code of the start tag with parameters as a string.

E.g. the following tag:

{% slot "content" default required %}
  <div>
    ...
  </div>
{% endslot %}

The start_tag_source will be "{% slot "content" default required %}".

May be None if the Node instance was created manually.

flags: dict[str, bool]

Dictionary of all allowed_flags that were set on the tag.

Flags that were set are True, and the rest are False.

E.g. the following tag:

class SlotNode(BaseNode):
    tag = "slot"
    end_tag = "endslot"
    allowed_flags = ["default", "required"]

{% slot "content" default %}

Has 2 flags, default and required, but only default was set.

The flags dictionary will be:

{
    "default": True,
    "required": False,
}

You can check if a flag is set by doing:

if node.flags["default"]:
    ...

filters: dict[str, Callable]

The filters available to the tag.

This will be the same as the global Django filters.

tags: dict[str, Callable]

The tags available to the tag.

This will be the same as the global Django tags.

nodelist: NodeList

The nodelist of the tag.

This is the text between the opening and closing tags, e.g.

{% slot "content" default required %}
  <div>
    ...
  </div>
{% endslot %}

The nodelist will contain the <div> ... </div> part.

Unlike contents, the nodelist contains the actual Nodes, not just the text.

contents: str | None

The body of the tag as a string.

This is the text between the opening and closing tags, e.g.

{% slot "content" default required %}
  <div>
    ...
  </div>
{% endslot %}

The contents will be "<div> ... </div>".

node_id: str

The unique ID of the node.

Extensions can use this ID to store additional information.

template_name: str | None

The name of the Template that contains this node.

The template name is set by Django's template loaders.

For example, the filesystem template loader will set this to the absolute path of the template file.

"/home/user/project/templates/my_template.html"

template_component: type[Component] | None

If the template that contains this node belongs to a Component, then this will be the Component class.

active_flags: list[str]

Flags that were set for this specific instance as a list of strings.

E.g. the following tag:

{% slot "content" default required / %}

Will have the following flags:

["default", "required"]

render(
context: Context,
*_args: Any = (),
**_kwargs: Any = {}
) -> str

See source code

Render the node. This method is meant to be overridden by subclasses.

The signature of this function decides what input the template tag accepts.

The render() method MUST accept a context argument. Any arguments after that will be part of the tag's input parameters.

So if you define a render method like this:

def render(self, context: Context, name: str, **kwargs: Any) -> str:

Then the tag will require the name parameter, and accept any extra keyword arguments:

{% component name="John" age=20 %}

parse(
parser: Parser,
token: Token,
**kwargs: Any = {}
) -> BaseNode

See source code

This function is what is passed to Django's Library.tag() when registering the tag.

In other words, this method is called by Django's template parser when we encounter a tag that matches this node's tag, e.g. {% component %} or {% slot %}.

To register the tag, you can use BaseNode.register().

register(library: Library) -> None

See source code

A convenience method for registering the tag with the given library.

class MyNode(BaseNode):
    tag = "mynode"

MyNode.register(library)

Allows you to then use the node in templates like so:

{% load mylibrary %}
{% mynode %}

unregister(library: Library) -> None

See source code

Unregisters the node from the given library.

Args: type | None

Optional typing for positional arguments passed to the component.

If set and not None, then the args parameter of the data methods (get_template_data(), get_js_data(), get_css_data()) will be the instance of this class:

from django_components import Component

class Table(Component):
    class Args:
        color: str
        size: int

    def get_template_data(self, args: Args, kwargs, slots, context):
        assert isinstance(args, Table.Args)

        return {
            "color": args.color,
            "size": args.size,
        }

Use Args to:

• Validate the input at runtime.
• Set type hints for the positional arguments for data methods like get_template_data().
• Document the component inputs.

You can also use Args to validate the positional arguments for Component.render():

Table.render(
    args=Table.Args(color="red", size=10),
)

If you do not specify any bases, the Args class will be automatically converted to a NamedTuple:

class Args: -> class Args(NamedTuple):

If you explicitly set bases, the constructor of this class MUST accept positional arguments:

Args(*args)

As such, a good starting point is to set this field to a subclass of NamedTuple.

Read more on Typing and validation.

Kwargs: type | None

Optional typing for keyword arguments passed to the component.

If set and not None, then the kwargs parameter of the data methods (get_template_data(), get_js_data(), get_css_data()) will be the instance of this class:

from django_components import Component

class Table(Component):
    class Kwargs:
        color: str
        size: int = 10

    def get_template_data(self, args, kwargs: Kwargs, slots, context):
        assert isinstance(kwargs, Table.Kwargs)

        return {
            "color": kwargs.color,
            "size": kwargs.size,
        }

Use Kwargs to:

• Validate the input at runtime.
• Set type hints for the keyword arguments for data methods like get_template_data().
• Set defaults for individual fields
• Document the component inputs.

You can also use Kwargs to validate the keyword arguments for Component.render():

Table.render(
    kwargs=Table.Kwargs(color="red", size=10),
)

The defaults set on Kwargs will be merged with defaults from Component.Defaults class. Kwargs takes precendence. Read more about Component defaults.

If you do not specify any bases, the Kwargs class will be automatically converted to a NamedTuple:

class Kwargs: -> class Kwargs(NamedTuple):

If you explicitly set bases, the constructor of this class MUST accept keyword arguments:

Kwargs(**kwargs)

As such, a good starting point is to set this field to a subclass of NamedTuple or a dataclass.

Read more on Typing and validation.

Slots: type | None

Optional typing for slots passed to the component.

If set and not None, then the slots parameter of the data methods (get_template_data(), get_js_data(), get_css_data()) will be the instance of this class:

from django_components import Component, Slot, SlotInput

class Table(Component):
    class Slots:
        header: SlotInput
        footer: Slot

    def get_template_data(self, args, kwargs, slots: Slots, context):
        assert isinstance(slots, Table.Slots)

        return {
            "header": slots.header,
            "footer": slots.footer,
        }

Use Slots to:

• Validate the input at runtime.
• Set type hints for the slots for data methods like get_template_data().
• Document the component inputs.

You can also use Slots to validate the slots for Component.render():

Table.render(
    slots=Table.Slots(
        header="HELLO IM HEADER",
        footer=Slot(lambda ctx: ...),
    ),
)

If you do not specify any bases, the Slots class will be automatically converted to a NamedTuple:

class Slots: -> class Slots(NamedTuple):

If you explicitly set bases, the constructor of this class MUST accept keyword arguments:

Slots(**slots)

As such, a good starting point is to set this field to a subclass of NamedTuple or a dataclass.

Read more on Typing and validation.

template_file: str | None

Filepath to the Django template associated with this component.

The filepath must be either:

• Relative to the directory where the Component's Python file is defined.
• Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
• Relative to the template directories, as set by Django's TEMPLATES setting (e.g. <root>/templates/).

|- components/
  |- table/
    |- table.html
    |- table.css
    |- table.js

class Table(Component):
    template_file = "table.html"

class Table(Component):
    template_file = "table/table.html"

template_name: str | None

Alias for template_file.

For historical reasons, django-components used template_name to align with Django's TemplateView.

template_file was introduced to align with js/js_file and css/css_file.

Setting and accessing this attribute is proxied to template_file.

template: str | None

Inlined Django template (as a plain string) associated with this component.

class Table(Component):
    template = '''
      <div>
        {{ my_var }}
      </div>
    '''

from django_components import Component, types

class MyComponent(Component):
    template: types.django_html = '''
      <div>
        {{ my_var }}
      </div>
    '''

TemplateData: type | None

Optional typing for the data to be returned from get_template_data().

If set and not None, then this class will be instantiated with the dictionary returned from get_template_data() to validate the data.

Use TemplateData to:

• Validate the data returned from get_template_data() at runtime.
• Set type hints for this data.
• Document the component data.

You can also return an instance of TemplateData directly from get_template_data() to get type hints:

from django_components import Component

class Table(Component):
    class TemplateData:
        color: str
        size: int

    def get_template_data(self, args, kwargs, slots, context):
        return Table.TemplateData(
            color=kwargs["color"],
            size=kwargs["size"],
        )

The constructor of this class MUST accept keyword arguments:

TemplateData(**template_data)

A good starting point is to set this field to a subclass of NamedTuple or a dataclass.

Read more on Typing and validation.

js: str | None

Main JS associated with this component inlined as string.

class MyComponent(Component):
    js = "console.log('Hello, World!');"

Syntax highlighting

When using the inlined template, you can enable syntax highlighting with django_components.types.js.

Learn more about syntax highlighting.

from django_components import Component, types

class MyComponent(Component):
    js: types.js = '''
        console.log('Hello, World!');
    '''

js_file: str | None

Main JS associated with this component as file path.

The filepath must be either:

• Relative to the directory where the Component's Python file is defined.
• Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
• Relative to the staticfiles directories, as set by Django's STATICFILES_DIRS setting (e.g. <root>/static/).

When you create a Component class with js_file, these will happen:

1. If the file path is relative to the directory where the component's Python file is, the path is resolved.
2. The file is read and its contents is set to Component.js.

console.log('Hello, World!');

class MyComponent(Component):
    js_file = "path/to/script.js"

print(MyComponent.js)
# Output: console.log('Hello, World!');

JsData: type | None

Optional typing for the data to be returned from get_js_data().

If set and not None, then this class will be instantiated with the dictionary returned from get_js_data() to validate the data.

Use JsData to:

• Validate the data returned from get_js_data() at runtime.
• Set type hints for this data.
• Document the component data.

You can also return an instance of JsData directly from get_js_data() to get type hints:

from django_components import Component

class Table(Component):
    class JsData(
        color: str
        size: int

    def get_js_data(self, args, kwargs, slots, context):
        return Table.JsData(
            color=kwargs["color"],
            size=kwargs["size"],
        )

The constructor of this class MUST accept keyword arguments:

JsData(**js_data)

A good starting point is to set this field to a subclass of NamedTuple or a dataclass.

Read more on Typing and validation.

css: str | None

Main CSS associated with this component inlined as string.

class MyComponent(Component):
    css = """
        .my-class {
            color: red;
        }
    """

Syntax highlighting

When using the inlined template, you can enable syntax highlighting with django_components.types.css.

Learn more about syntax highlighting.

from django_components import Component, types

class MyComponent(Component):
    css: types.css = '''
      .my-class {
        color: red;
      }
    '''

css_file: str | None

Main CSS associated with this component as file path.

The filepath must be either:

• Relative to the directory where the Component's Python file is defined.
• Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
• Relative to the staticfiles directories, as set by Django's STATICFILES_DIRS setting (e.g. <root>/static/).

When you create a Component class with css_file, these will happen:

1. If the file path is relative to the directory where the component's Python file is, the path is resolved.
2. The file is read and its contents is set to Component.css.

.my-class {
    color: red;
}

class MyComponent(Component):
    css_file = "path/to/style.css"

print(MyComponent.css)
# Output:
# .my-class {
#     color: red;
# };

CssData: type | None

Optional typing for the data to be returned from get_css_data().

If set and not None, then this class will be instantiated with the dictionary returned from get_css_data() to validate the data.

Use CssData to:

• Validate the data returned from get_css_data() at runtime.
• Set type hints for this data.
• Document the component data.

You can also return an instance of CssData directly from get_css_data() to get type hints:

from django_components import Component

class Table(Component):
    class CssData:
        color: str
        size: int

    def get_css_data(self, args, kwargs, slots, context):
        return Table.CssData(
            color=kwargs["color"],
            size=kwargs["size"],
        )

The constructor of this class MUST accept keyword arguments:

CssData(**css_data)

A good starting point is to set this field to a subclass of NamedTuple or a dataclass.

Read more on Typing and validation.

media: MediaCls | None

Normalized definition of JS and CSS media files associated with this component. None if Component.Media is not defined.

This field is generated from Component.media_class.

Read more on Accessing component's Media JS / CSS.

class MyComponent(Component):
    class Media:
        js = "path/to/script.js"
        css = "path/to/style.css"

print(MyComponent.media)
# Output:
# <script src="/static/path/to/script.js"></script>
# <link href="/static/path/to/style.css" media="all" rel="stylesheet">

media_class: type[MediaCls]

Set the Media class that will be instantiated with the JS and CSS media files from Component.Media.

This is useful when you want to customize the behavior of the media files, like customizing how the JS or CSS files are rendered into <script> or <link> HTML tags.

Read more in Media class.

class MyTable(Component):
    class Media:
        js = "path/to/script.js"
        css = "path/to/style.css"

    media_class = MyMediaClass

Media: type[ComponentMediaInput] | None

Defines JS and CSS media files associated with this component.

This Media class behaves similarly to Django's Media class:

• Paths are generally handled as static file paths, and resolved URLs are rendered to HTML with media_class.render_js() or media_class.render_css().
• A path that starts with http, https, or / is considered a URL, skipping the static file resolution. This path is still rendered to HTML with media_class.render_js() or media_class.render_css().
• A SafeString (with __html__ method) is considered an already-formatted HTML tag, skipping both static file resolution and rendering with media_class.render_js() or media_class.render_css().
• You can set extend to configure whether to inherit JS / CSS from parent components. See Media inheritance.

However, there's a few differences from Django's Media class:

1. Our Media class accepts various formats for the JS and CSS files: either a single file, a list, or (CSS-only) a dictionary (See ComponentMediaInput).
2. Individual JS / CSS files can be any of str, bytes, Path, SafeString, or a function (See ComponentMediaInputPath).

class MyTable(Component):
    class Media:
        js = [
            "path/to/script.js",
            "https://unpkg.com/alpinejs@3.14.7/dist/cdn.min.js",  # AlpineJS
        ]
        css = {
            "all": [
                "path/to/style.css",
                "https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css",  # TailwindCSS
            ],
            "print": ["path/to/style2.css"],
        }

response_class: type[HttpResponse]

This attribute configures what class is used to generate response from Component.render_to_response().

The response class should accept a string as the first argument.

Defaults to django.http.HttpResponse.

from django.http import HttpResponse
from django_components import Component

class MyHttpResponse(HttpResponse):
    ...

class MyComponent(Component):
    response_class = MyHttpResponse

response = MyComponent.render_to_response()
assert isinstance(response, MyHttpResponse)

Cache: type[ComponentCache]

The fields of this class are used to configure the component caching.

Read more about Component caching.

from django_components import Component

class MyComponent(Component):
    class Cache:
        enabled = True
        ttl = 60 * 60 * 24  # 1 day
        cache_name = "my_cache"

cache: ComponentCache

Instance of ComponentCache available at component render time.

Defaults: type[ComponentDefaults]

The fields of this class are used to set default values for the component's kwargs.

These defaults will be merged with defaults on Component.Kwargs.

Read more about Component defaults.

from django_components import Component, Default

class MyComponent(Component):
    class Defaults:
        position = "left"
        selected_items = Default(lambda: [1, 2, 3])

defaults: ComponentDefaults

Instance of ComponentDefaults available at component render time.

View: type[ComponentView]

The fields of this class are used to configure the component views and URLs.

This class is a subclass of django.views.View. The Component instance is available via self.component.

Override the methods of this class to define the behavior of the component.

Read more about Component views and URLs.

class MyComponent(Component):
    class View:
        def get(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
            return HttpResponse("Hello, world!")

view: ComponentView

Instance of ComponentView available at component render time.

DebugHighlight: type[ComponentDebugHighlight]

The fields of this class are used to configure the component debug highlighting.

Read more about Component debug highlighting.

name: str

The name of the component.

If the component was registered, this will be the name under which the component was registered in the ComponentRegistry.

Otherwise, this will be the name of the class.

@register("my_component")
class RegisteredComponent(Component):
    def get_template_data(self, args, kwargs, slots, context):
        return {
            "name": self.name,  # "my_component"
        }

class UnregisteredComponent(Component):
    def get_template_data(self, args, kwargs, slots, context):
        return {
            "name": self.name,  # "UnregisteredComponent"
        }

registered_name: str | None

If the component was rendered with the {% component %} template tag, this will be the name under which the component was registered in the ComponentRegistry.

Otherwise, this will be None.

@register("my_component")
class MyComponent(Component):
    template = "{{ name }}"

    def get_template_data(self, args, kwargs, slots, context):
        return {
            "name": self.registered_name,
        }

{% component "my_component" / %}

MyComponent.render()
# None

id: str

This ID is unique for every time a Component.render() (or equivalent) is called (AKA "render ID").

This is useful for logging or debugging.

The ID is a 7-letter alphanumeric string in the format cXXXXXX, where XXXXXX is a random string of 6 alphanumeric characters (case-sensitive).

E.g. c1A2b3c.

A single render ID has a chance of collision 1 in 57 billion. However, due to birthday paradox, the chance of collision increases to 1% when approaching ~33K render IDs.

Thus, there is currently a soft-cap of ~30K components rendered on a single page.

If you need to expand this limit, please open an issue on GitHub.

class MyComponent(Component):
    def get_template_data(self, args, kwargs, slots, context):
        print(f"Rendering '{self.id}'")

MyComponent.render()
# Rendering 'ab3c4d'

input: ComponentInput

Deprecated. Will be removed in v1.

Input holds the data that were passed to the current component at render time.

This includes:

• args - List of positional arguments
• kwargs - Dictionary of keyword arguments
• slots - Dictionary of slots. Values are normalized to Slot instances
• context - Context object that should be used to render the component
• And other kwargs passed to Component.render() like deps_strategy

class Table(Component):
    def get_template_data(self, args, kwargs, slots, context):
        # Access component's inputs, slots and context
        assert self.args == [123, "str"]
        assert self.kwargs == {"variable": "test", "another": 1}
        footer_slot = self.slots["footer"]
        some_var = self.input.context["some_var"]

rendered = TestComponent.render(
    kwargs={"variable": "test", "another": 1},
    args=[123, "str"],
    slots={"footer": "MY_SLOT"},
)

args: Any

Positional arguments passed to the component.

This is part of the Render API.

args has the same behavior as the args argument of Component.get_template_data():

• If you defined the Component.Args class, then the args property will return an instance of that Args class.
• Otherwise, args will be a plain list.

from django_components import Component

class Table(Component):
    class Args:
        page: int
        per_page: int

    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert self.args.page == 123
        assert self.args.per_page == 10

rendered = Table.render(
    args=[123, 10],
)

from django_components import Component

class Table(Component):
    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert self.args[0] == 123
        assert self.args[1] == 10

raw_args: list[Any]

Positional arguments passed to the component.

This is part of the Render API.

Unlike Component.args, this attribute is not typed and will remain as plain list even if you define the Component.Args class.

from django_components import Component

class Table(Component):
    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert self.raw_args[0] == 123
        assert self.raw_args[1] == 10

kwargs: Any

Keyword arguments passed to the component.

This is part of the Render API.

kwargs has the same behavior as the kwargs argument of Component.get_template_data():

• If you defined the Component.Kwargs class, then the kwargs property will return an instance of that Kwargs class.
• Otherwise, kwargs will be a plain dict.

Kwargs have the defaults applied to them. Read more about Component defaults.

from django_components import Component

class Table(Component):
    class Kwargs:
        page: int
        per_page: int

    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert self.kwargs.page == 123
        assert self.kwargs.per_page == 10

rendered = Table.render(
    kwargs={
        "page": 123,
        "per_page": 10,
    },
)

from django_components import Component

class Table(Component):
    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert self.kwargs["page"] == 123
        assert self.kwargs["per_page"] == 10

raw_kwargs: dict[str, Any]

Keyword arguments passed to the component.

This is part of the Render API.

Unlike Component.kwargs, this attribute is not typed and will remain as plain dict even if you define the Component.Kwargs class.

raw_kwargs have the defaults applied to them. Read more about Component defaults.

from django_components import Component

class Table(Component):
    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert self.raw_kwargs["page"] == 123
        assert self.raw_kwargs["per_page"] == 10

slots: Any

Slots passed to the component.

This is part of the Render API.

slots has the same behavior as the slots argument of Component.get_template_data():

• If you defined the Component.Slots class, then the slots property will return an instance of that class.
• Otherwise, slots will be a plain dict.

from django_components import Component, Slot, SlotInput

class Table(Component):
    class Slots:
        header: SlotInput
        footer: SlotInput

    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert isinstance(self.slots.header, Slot)
        assert isinstance(self.slots.footer, Slot)

rendered = Table.render(
    slots={
        "header": "MY_HEADER",
        "footer": lambda ctx: "FOOTER: " + ctx.data["user_id"],
    },
)

from django_components import Component, Slot, SlotInput

class Table(Component):
    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert isinstance(self.slots["header"], Slot)
        assert isinstance(self.slots["footer"], Slot)

raw_slots: dict[str, Slot]

Slots passed to the component.

This is part of the Render API.

Unlike Component.slots, this attribute is not typed and will remain as plain dict even if you define the Component.Slots class.

from django_components import Component

class Table(Component):
    def on_render_before(self, context: Context, template: Template | None) -> None:
        assert self.raw_slots["header"] == "MY_HEADER"
        assert self.raw_slots["footer"] == "FOOTER: " + ctx.data["user_id"]

context: Context

The context argument as passed to Component.get_template_data().

This is Django's Context with which the component template is rendered.

If the root component or template was rendered with RequestContext then this will be an instance of RequestContext.

Whether the context variables defined in context are available to the template depends on the context behavior mode:

• In "django" context behavior mode, the template will have access to the keys of this context.

• In "isolated" context behavior mode, the template will NOT have access to this context, and data MUST be passed via component's args and kwargs.

deps_strategy: DependenciesStrategy

Dependencies strategy defines how to handle JS and CSS dependencies of this and child components.

Read more about Dependencies rendering.

This is part of the Render API.

There are six strategies:

• "document" (default)
  • Smartly inserts JS / CSS into placeholders or into <head> and <body> tags.
  • Requires the HTML to be rendered in a JS-enabled browser.
  • Inserts extra script for managing fragments.
• "fragment"
  • A lightweight HTML fragment to be inserted into a document with AJAX.
  • Fragment will fetch its own JS / CSS dependencies when inserted into the page.
  • Requires the HTML to be rendered in a JS-enabled browser.
• "simple"
  • Smartly insert JS / CSS into placeholders or into <head> and <body> tags.
  • No extra script loaded.
• "prepend"
  • Insert JS / CSS before the rendered HTML.
  • No extra script loaded.
• "append"
  • Insert JS / CSS after the rendered HTML.
  • No extra script loaded.
• "ignore"
  • HTML is left as-is. You can still process it with a different strategy later with render_dependencies().
  • Used for inserting rendered HTML into other components.

outer_context: Context | None

When a component is rendered with the {% component %} tag, this is the Django's Context object that was used just outside of the component.

{% with abc=123 %}
    {{ abc }} {# <--- This is in outer context #}
    {% component "my_component" / %}
{% endwith %}

This is relevant when your components are isolated, for example when using the "isolated" context behavior mode or when using the only flag.

When components are isolated, each component has its own instance of Context, so outer_context is different from the context argument.

registry: ComponentRegistry

The ComponentRegistry instance that was used to render the component.

node: ComponentNode | None

The ComponentNode instance that was used to render the component.

This will be set only if the component was rendered with the {% component %} tag.

Accessing the ComponentNode is mostly useful for extensions, which can modify their behaviour based on the source of the Component.

class MyComponent(Component):
    def get_template_data(self, context, template):
        if self.node is not None:
            assert self.node.name == "my_component"

For example, if MyComponent was used in another component - that is, with a {% component "my_component" %} tag in a template that belongs to another component - then you can use self.node.template_component to access the owner Component class.

class Parent(Component):
    template: types.django_html = '''
        <div>
            {% component "my_component" / %}
        </div>
    '''

@register("my_component")
class MyComponent(Component):
    def get_template_data(self, context, template):
        if self.node is not None:
            assert self.node.template_component == Parent

is_filled: SlotIsFilled

Deprecated. Will be removed in v1. Use Component.slots instead. Note that Component.slots no longer escapes the slot names.

Dictionary describing which slots have or have not been filled.

This attribute is available for use only within:

You can also access this variable from within the template as

{{ component_vars.is_filled.slot_name }}

request: HttpRequest | None

HTTPRequest object passed to this component.

class MyComponent(Component):
    def get_template_data(self, args, kwargs, slots, context):
        user_id = self.request.GET['user_id']
        return {
            'user_id': user_id,
        }

Passing request to a component:

In regular Django templates, you have to use RequestContext to pass the HttpRequest object to the template.

With Components, you can either use RequestContext, or pass the request object explicitly via Component.render() and Component.render_to_response().

When a component is nested in another, the child component uses parent's request object.

context_processors_data: dict

Retrieve data injected by context_processors.

This data is also available from within the component's template, without having to return this data from get_template_data().

In regular Django templates, you need to use RequestContext to apply context processors.

In Components, the context processors are applied to components either when:

• The component is rendered with RequestContext (Regular Django behavior)
• The component is rendered with a regular Context (or none), but the request kwarg of Component.render() is set.
• The component is nested in another component that matches any of these conditions.

See Component.request on how the request (HTTPRequest) object is passed to and within the components.

NOTE: This dictionary is generated dynamically, so any changes to it will not be persisted.

class MyComponent(Component):
    def get_template_data(self, args, kwargs, slots, context):
        user = self.context_processors_data['user']
        return {
            'is_logged_in': user.is_authenticated,
        }

parent: Component | None

The parent component instance of the current component.

This is part of the Render API.

Returns the parent Component instance if this component is nested within another component, or None if this is the root component.

class Theme(Component):
    ...

class Table(Component):
    def on_render_before(self, context, template):
        if self.parent is not None:
            # This component is nested in another component
            parent_type = type(self.parent).__name__
            ...

root: Component

The root component instance (top-most ancestor) of the current component.

This is part of the Render API.

Returns the root Component instance in the component tree. If this component is the root component, returns self.

class Theme(Component):
    ...

class Table(Component):
    def get_template_data(self, args, kwargs, slots, context):
        # Access root component's data
        root_kwargs = self.root.kwargs
        ...

ancestors: Generator[Component, None, None]

An iterator that yields all ancestor component instances, walking up the tree.

This is part of the Render API.

Yields Component instances starting from the parent component, then the parent's parent, and so on, up to (but not including) the root component.

class Theme(Component):
    ...

class MarkdownEditor(Component):
    def get_template_data(self, args, kwargs, slots, context):
        # Check if this component is nested in a Theme component
        is_nested_in_theme = any(
            isinstance(comp, Theme) for comp in self.ancestors
        )
        if is_nested_in_theme:
            css_fix = "width: 200px; display: flex"
        else:
            css_fix = ""

        return {
            "css_fix": css_fix,
        }

class_id: str

Unique ID of the component class, e.g. MyComponent_ab01f2.

This is derived from the component class' module import path, e.g. path.to.my.MyComponent.

do_not_call_in_templates: bool

Django special property to prevent calling the instance as a function inside Django templates.

Read more about Django's do_not_call_in_templates.

get_template_name(context: Context) -> str | None

See source code

DEPRECATED: Use instead Component.template_file, Component.template or Component.on_render(). Will be removed in v1.

Same as Component.template_file, but allows to dynamically resolve the template name at render time.

See Component.template_file for more info and examples.

get_template(context: Context) -> str | Template | None

See source code

DEPRECATED: Use instead Component.template_file, Component.template or Component.on_render(). Will be removed in v1.

Same as Component.template, but allows to dynamically resolve the template at render time.

The template can be either plain string or a Template instance.

See Component.template for more info and examples.

get_context_data(*_args: Any = (), **_kwargs: Any = {}) -> Mapping | None

See source code

DEPRECATED: Use get_template_data() instead. Will be removed in v2.

Use this method to define variables that will be available in the template.

Receives the args and kwargs as they were passed to the Component.

This method has access to the Render API.

Read more about Template variables.

class MyComponent(Component):
    def get_context_data(self, name, *args, **kwargs):
        return {
            "name": name,
            "id": self.id,
        }

    template = "Hello, {{ name }}!"

MyComponent.render(name="World")

get_template_data(
    args: Any,
    kwargs: Any,
    slots: Any,
    context: Context
) -> Mapping | None

See source code

Use this method to define variables that will be available in the template.

This method has access to the Render API.

Read more about Template variables.

class MyComponent(Component):
    def get_template_data(self, args, kwargs, slots, context):
        return {
            "name": kwargs["name"],
            "id": self.id,
        }

    template = "Hello, {{ name }}!"

MyComponent.render(name="World")

Pass-through kwargs:

It's best practice to explicitly define what args and kwargs a component accepts.

However, if you want a looser setup, you can easily write components that accept any number of kwargs, and pass them all to the template (similar to django-cotton).

To do that, simply return the kwargs dictionary itself from get_template_data():

class MyComponent(Component):
    def get_template_data(self, args, kwargs, slots, context):
        return kwargs

Type hints:

To get type hints for the args, kwargs, and slots parameters, you can define the Args, Kwargs, and Slots classes on the component class, and then directly reference them in the function signature of get_template_data().

When you set these classes, the args, kwargs, and slots parameters will be given as instances of these (args instance of Args, etc).

When you omit these classes, or set them to None, then the args, kwargs, and slots parameters will be given as plain lists / dictionaries, unmodified.

Read more on Typing and validation.

from django.template import Context
from django_components import Component, SlotInput

class MyComponent(Component):
    class Args:
        color: str

    class Kwargs:
        size: int

    class Slots:
        footer: SlotInput

    def get_template_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context):
        assert isinstance(args, MyComponent.Args)
        assert isinstance(kwargs, MyComponent.Kwargs)
        assert isinstance(slots, MyComponent.Slots)

        return {
            "color": args.color,
            "size": kwargs.size,
            "id": self.id,
        }

You can also add typing to the data returned from get_template_data() by defining the TemplateData class on the component class.

When you set this class, you can return either the data as a plain dictionary, or an instance of TemplateData.

If you return plain dictionary, the data will be validated against the TemplateData class by instantiating it with the dictionary.

class MyComponent(Component):
    class TemplateData:
        color: str
        size: int

    def get_template_data(self, args, kwargs, slots, context):
        return {
            "color": kwargs["color"],
            "size": kwargs["size"],
        }
        # or
        return MyComponent.TemplateData(
            color=kwargs["color"],
            size=kwargs["size"],
        )

get_js_data(
    args: Any,
    kwargs: Any,
    slots: Any,
    context: Context
) -> Mapping | None

See source code

Use this method to define variables that will be available from within the component's JavaScript code.

This method has access to the Render API.

The data returned from this method will be serialized to JSON.

Read more about JavaScript variables.

class MyComponent(Component):
    def get_js_data(self, args, kwargs, slots, context):
        return {
            "name": kwargs["name"],
            "id": self.id,
        }

    js = '''
        $onComponent(({ name, id }, ctx) => {
            console.log(name, id);
        });
    '''

MyComponent.render(name="World")

Pass-through kwargs:

It's best practice to explicitly define what args and kwargs a component accepts.

However, if you want a looser setup, you can easily write components that accept any number of kwargs, and pass them all to the JavaScript code.

To do that, simply return the kwargs dictionary itself from get_js_data():

class MyComponent(Component):
    def get_js_data(self, args, kwargs, slots, context):
        return kwargs

Type hints:

To get type hints for the args, kwargs, and slots parameters, you can define the Args, Kwargs, and Slots classes on the component class, and then directly reference them in the function signature of get_js_data().

When you set these classes, the args, kwargs, and slots parameters will be given as instances of these (args instance of Args, etc).

When you omit these classes, or set them to None, then the args, kwargs, and slots parameters will be given as plain lists / dictionaries, unmodified.

Read more on Typing and validation.

from typing import NamedTuple
from django.template import Context
from django_components import Component, SlotInput

class MyComponent(Component):
    class Args:
        color: str

    class Kwargs:
        size: int

    class Slots:
        footer: SlotInput

    def get_js_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context):
        assert isinstance(args, MyComponent.Args)
        assert isinstance(kwargs, MyComponent.Kwargs)
        assert isinstance(slots, MyComponent.Slots)

        return {
            "color": args.color,
            "size": kwargs.size,
            "id": self.id,
        }

You can also add typing to the data returned from get_js_data() by defining the JsData class on the component class.

When you set this class, you can return either the data as a plain dictionary, or an instance of JsData.

If you return plain dictionary, the data will be validated against the JsData class by instantiating it with the dictionary.

class MyComponent(Component):
    class JsData:
        color: str
        size: int

    def get_js_data(self, args, kwargs, slots, context):
        return {
            "color": kwargs["color"],
            "size": kwargs["size"],
        }
        # or
        return MyComponent.JsData(
            color=kwargs["color"],
            size=kwargs["size"],
        )

get_css_data(
args: Any,
kwargs: Any,
slots: Any,
context: Context
) -> Mapping | None

See source code

Use this method to define variables that will be available from within the component's CSS code.

This method has access to the Render API.

The data returned from this method will be serialized to string.

Read more about CSS variables.

class MyComponent(Component):
    def get_css_data(self, args, kwargs, slots, context):
        return {
            "color": kwargs["color"],
        }

    css = '''
        .my-class {
            color: var(--color);
        }
    '''

MyComponent.render(color="red")

Pass-through kwargs:

It's best practice to explicitly define what args and kwargs a component accepts.

However, if you want a looser setup, you can easily write components that accept any number of kwargs, and pass them all to the CSS code.

To do that, simply return the kwargs dictionary itself from get_css_data():

class MyComponent(Component):
    def get_css_data(self, args, kwargs, slots, context):
        return kwargs

Type hints:

To get type hints for the args, kwargs, and slots parameters, you can define the Args, Kwargs, and Slots classes on the component class, and then directly reference them in the function signature of get_css_data().

When you set these classes, the args, kwargs, and slots parameters will be given as instances of these (args instance of Args, etc).

When you omit these classes, or set them to None, then the args, kwargs, and slots parameters will be given as plain lists / dictionaries, unmodified.

Read more on Typing and validation.

from django.template import Context
from django_components import Component, SlotInput

class MyComponent(Component):
    class Args:
        color: str

    class Kwargs:
        size: int

    class Slots:
        footer: SlotInput

    def get_css_data(self, args: Args, kwargs: Kwargs, slots: Slots, context: Context):
        assert isinstance(args, MyComponent.Args)
        assert isinstance(kwargs, MyComponent.Kwargs)
        assert isinstance(slots, MyComponent.Slots)

        return {
            "color": args.color,
            "size": kwargs.size,
        }

You can also add typing to the data returned from get_css_data() by defining the CssData class on the component class.

When you set this class, you can return either the data as a plain dictionary, or an instance of CssData.

If you return plain dictionary, the data will be validated against the CssData class by instantiating it with the dictionary.

class MyComponent(Component):
    class CssData:
        color: str
        size: int

    def get_css_data(self, args, kwargs, slots, context):
        return {
            "color": kwargs["color"],
            "size": kwargs["size"],
        }
        # or
        return MyComponent.CssData(
            color=kwargs["color"],
            size=kwargs["size"],
        )

on_render_before(context: Context, template: Template | None) -> None

See source code

Runs just before the component's template is rendered.

It is called for every component, including nested ones, as part of the component render lifecycle.

from django.template import Context, Template
from django_components import Component

class MyTable(Component):
    def on_render_before(self, context: Context, template: Template | None) -> None:
        # Insert value into the Context
        context["from_on_before"] = ":)"

        assert isinstance(template, Template)

on_render(context: Context, template: Template | None) -> SlotResult | OnRenderGenerator | None

See source code

This method does the actual rendering.

Read more about this hook in Component hooks.

You can override this method to:

• Change what template gets rendered
• Modify the context
• Modify the rendered output after it has been rendered
• Handle errors

The default implementation renders the component's Template with the given Context.

class MyTable(Component):
    def on_render(self, context, template):
        if template is None:
            return None
        else:
            return template.render(context)

The template argument is None if the component has no template.

Modifying rendered template

To change what gets rendered, you can:

• Render a different template
• Render a component
• Return a different string or SafeString

class MyTable(Component):
    def on_render(self, context, template):
        return "Hello"

Post-processing rendered template

To access the final output, you can yield the result instead of returning it.

This will return a tuple of (rendered HTML, error). The error is None if the rendering succeeded.

class MyTable(Component):
    def on_render(self, context, template):
        html, error = yield lambda: template.render(context)

        if error is None:
            # The rendering succeeded
            return html
        else:
            # The rendering failed
            print(f"Error: {error}")

At this point you can do 3 things:

1. Return a new HTML

   The new HTML will be used as the final output.

   If the original template raised an error, it will be ignored.

   class MyTable(Component):
       def on_render(self, context, template):
           html, error = yield lambda: template.render(context)
   
           return "NEW HTML"
   

2. Raise a new exception

   The new exception is what will bubble up from the component.

   The original HTML and original error will be ignored.

   class MyTable(Component):
       def on_render(self, context, template):
           html, error = yield lambda: template.render(context)
   
           raise Exception("Error message")
   

3. Return nothing (or None) to handle the result as usual

   If you don't raise an exception, and neither return a new HTML, then original HTML / error will be used:

   • If rendering succeeded, the original HTML will be used as the final output.
   • If rendering failed, the original error will be propagated.

   class MyTable(Component):
       def on_render(self, context, template):
           html, error = yield lambda: template.render(context)
   
           if error is not None:
               # The rendering failed
               print(f"Error: {error}")
   

Multiple yields

You can yield multiple times within the same on_render method. This is useful for complex rendering scenarios where you need to render different templates or handle multiple rendering operations:

class MyTable(Component):
    def on_render(self, context, template):
        # First yield - render with one context
        with context.push({"mode": "header"}):
            header_html, header_error = yield lambda: template.render(context)

        # Second yield - render with different context
        with context.push({"mode": "body"}):
            body_html, body_error = yield lambda: template.render(context)

        # Third yield - render a string directly
        footer_html, footer_error = yield "Footer content"

        # Process all results and return final output
        if header_error or body_error or footer_error:
            return "Error occurred during rendering"

        return f"{header_html}{body_html}{footer_html}"

Each yield operation is independent and returns its own (html, error) tuple, allowing you to handle each rendering result separately.

on_render_after(
    context: Context,
    template: Template | None,
    result: str | None,
    error: Exception | None
) -> SlotResult | None

See source code

Hook that runs when the component was fully rendered, including all its children.

It receives the same arguments as on_render_before(), plus the outcome of the rendering:

• result: The rendered output of the component. None if the rendering failed.
• error: The error that occurred during the rendering, or None if the rendering succeeded.

on_render_after() behaves the same way as the second part of on_render() (after the yield).

class MyTable(Component):
    def on_render_after(self, context, template, result, error):
        if error is None:
            # The rendering succeeded
            return result
        else:
            # The rendering failed
            print(f"Error: {error}")

Same as on_render(), you can return a new HTML, raise a new exception, or return nothing:

1. Return a new HTML

   The new HTML will be used as the final output.

   If the original template raised an error, it will be ignored.

   class MyTable(Component):
       def on_render_after(self, context, template, result, error):
           return "NEW HTML"
   

2. Raise a new exception

   The new exception is what will bubble up from the component.

   The original HTML and original error will be ignored.

   class MyTable(Component):
       def on_render_after(self, context, template, result, error):
           raise Exception("Error message")
   

3. Return nothing (or None) to handle the result as usual

   If you don't raise an exception, and neither return a new HTML, then original HTML / error will be used:

   • If rendering succeeded, the original HTML will be used as the final output.
   • If rendering failed, the original error will be propagated.

   class MyTable(Component):
       def on_render_after(self, context, template, result, error):
           if error is not None:
               # The rendering failed
               print(f"Error: {error}")
   

on_dependencies(scripts: list[Script], styles: list[Style]) -> tuple[list[Script], list[Style]] | None

See source code

Hook called once per rendered component instance with that component's Script/Style list.

The list includes Component.js/Component.css CSS/JS variables, and Component.Media.js/Component.Media.css.

Return (new_scripts, new_styles) to replace the list for this instance; return None (default) to keep the original list.

class MyButton(Component):
    @classmethod
    def on_dependencies(cls, scripts, styles):
        # Add a nonce to every inline style for this component
        for style in styles:
            if style.content and "nonce" not in style.attrs:
                style.attrs["nonce"] = get_current_nonce()
        return (scripts, styles)

inject(key: str, default: Any | None = None) -> Any

See source code

Use this method to retrieve the data that was passed to a {% provide %} tag with the corresponding key.