API¤

See source code

Flags that were set for this specific instance.

See source code

The allowed flags for this tag.

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

See source code

The end tag name.

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

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

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

See source code

The tag name.

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

See source code

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 typing import NamedTuple
from django_components import Component

class Table(Component):
    class Args(NamedTuple):
        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,
        }

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.

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),
)

Read more on Typing and validation.

See source code

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

Read more about Component caching.

Example:

from django_components import Component

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

See source code

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.

The constructor of this class MUST accept keyword arguments:

CssData(**css_data)

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

from typing import NamedTuple
from django_components import Component

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

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

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

Use CssData to:

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

Read more on Typing and validation.

See source code

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

Read more about Component defaults.

Example:

from django_components import Component, Default

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

See source code

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.

The constructor of this class MUST accept keyword arguments:

JsData(**js_data)

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

from typing import NamedTuple
from django_components import Component

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

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

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

Use JsData to:

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

Read more on Typing and validation.

See source code

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 typing import NamedTuple
from django_components import Component

class Table(Component):
    class Kwargs(NamedTuple):
        color: str
        size: int

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

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

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.

Use Kwargs to:

• Validate the input at runtime.
• Set type hints for the keyword arguments for data methods like get_template_data().
• 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),
)

Read more on Typing and validation.

See source code

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).

Example:

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"],
        }

See source code

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 typing import NamedTuple
from django_components import Component, Slot, SlotInput

class Table(Component):
    class Slots(NamedTuple):
        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,
        }

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.

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: ...),
    ),
)

Read more on Typing and validation.

See source code

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.

The constructor of this class MUST accept keyword arguments:

TemplateData(**template_data)

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

from typing import NamedTuple
from django_components import Component

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

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

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

Use TemplateData to:

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

Read more on Typing and validation.

See source code

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.

Example:

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

See source code

Instance of ComponentCache available at component render time.

See source code

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.

See source code

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.

Raises RuntimeError if accessed outside of rendering execution.

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

Example:

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,
        }

See source code

Main CSS associated with this component inlined as string.

Only one of css or css_file must be defined.

Example:

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

See source code

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.

Only one of css or css_file must be defined.

Example:

.my-class {
    color: red;
}

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

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

See source code

Instance of ComponentDefaults available at component render time.

See source code

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

This is useful for logging or debugging.

Raises RuntimeError if accessed outside of rendering execution.

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.

Example:

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

MyComponent.render()
# Rendering 'ab3c4d'

See source code

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

Raises RuntimeError if accessed outside of rendering execution.

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

Read more on Component inputs.

Example:

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

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

See source code

Dictionary describing which slots have or have not been filled.

This attribute is available for use only within the template as {{ component_vars.is_filled.slot_name }}, and within on_render_before and on_render_after hooks.

Raises RuntimeError if accessed outside of rendering execution.

See source code

Main JS associated with this component inlined as string.

Only one of js or js_file must be defined.

Example:

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

See source code

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.

Only one of js or js_file must be defined.

Example:

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

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

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

See source code

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 HTML / JS / CSS.

Example:

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">

See source code

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 Defining HTML / JS / CSS files.

Example:

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

    media_class = MyMediaClass

See source code

HTTPRequest object passed to this component.

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

But in 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.

Raises RuntimeError if accessed outside of rendering execution.

Example:

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

See source code

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.

Example:

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)

See source code

Inlined Django template associated with this component. Can be a plain string or a Template instance.

Only one of template_file, get_template_name, template or get_template must be defined.

Example:

class MyComponent(Component):
    template = "Hello, {{ name }}!"

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

See source code

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/).

Only one of template_file, get_template_name, template or get_template must be defined.

Example:

class MyComponent(Component):
    template_file = "path/to/template.html"

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

See source code

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.

See source code

Instance of ComponentView available at component render time.

See source code

The name of the cache to use. If None, the default cache will be used.

See source code

Whether this Component should be cached. Defaults to False.

See source code

The time-to-live (TTL) in seconds, i.e. for how long should an entry be valid in the cache.

• If > 0, the entries will be cached for the given number of seconds.
• If -1, the entries will be cached indefinitely.
• If 0, the entries won't be cached.
• If None, the default TTL will be used.

See source code

Base class that the "extension class" nested within a Component class will inherit from.

This is where you can define new methods and attributes that will be available to the component instance.

Background:

The extension may add new features to the Component class by allowing users to define and access a nested class in the Component class. E.g.:

class MyComp(Component):
    class MyExtension:
        ...

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

When rendering a component, the nested extension class will be set as a subclass of ExtensionClass. So it will be same as if the user had directly inherited from ExtensionClass. E.g.:

class MyComp(Component):
    class MyExtension(ComponentExtension.ExtensionClass):
        ...

This setting decides what the extension class will inherit from.

See source code

Name of the extension class.

By default, this is the same as name, but with snake_case converted to PascalCase.

So if the extension name is "my_extension", then the extension class name will be "MyExtension".

class MyComp(Component):
    class MyExtension:  # <--- This is the extension class
        ...

See source code

List of commands that can be run by the extension.

These commands will be available to the user as components ext run <extension> <command>.

Commands are defined as subclasses of ComponentCommand.

Example:

This example defines an extension with a command that prints "Hello world". To run the command, the user would run components ext run hello_world hello.

from django_components import ComponentCommand, ComponentExtension, CommandArg, CommandArgGroup

class HelloWorldCommand(ComponentCommand):
    name = "hello"
    help = "Hello world command."

    # Allow to pass flags `--foo`, `--bar` and `--baz`.
    # Argument parsing is managed by `argparse`.
    arguments = [
        CommandArg(
            name_or_flags="--foo",
            help="Foo description.",
        ),
        # When printing the command help message, `bar` and `baz`
        # will be grouped under "group bar".
        CommandArgGroup(
            title="group bar",
            description="Group description.",
            arguments=[
                CommandArg(
                    name_or_flags="--bar",
                    help="Bar description.",
                ),
                CommandArg(
                    name_or_flags="--baz",
                    help="Baz description.",
                ),
            ],
        ),
    ]

    # Callback that receives the parsed arguments and options.
    def handle(self, *args, **kwargs):
        print(f"HelloWorldCommand.handle: args={args}, kwargs={kwargs}")

# Associate the command with the extension
class HelloWorldExtension(ComponentExtension):
    name = "hello_world"

    commands = [
        HelloWorldCommand,
    ]

See source code

Name of the extension.

Name must be lowercase, and must be a valid Python identifier (e.g. "my_extension").

The extension may add new features to the Component class by allowing users to define and access a nested class in the Component class.

The extension name determines the name of the nested class in the Component class, and the attribute under which the extension will be accessible.

E.g. if the extension name is "my_extension", then the nested class in the Component class will be MyExtension, and the extension will be accessible as MyComp.my_extension.

class MyComp(Component):
    class MyExtension:
        ...

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