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

The basic type of action to be taken when this argument is encountered at the command line.

See source code

A sequence of the allowable values for the argument.

See source code

A constant value required by some action and nargs selections.

See source code

The value produced if the argument is absent from the command line and if it is absent from the namespace object.

See source code

Whether or not use of the argument is deprecated.

NOTE: This is supported only in Python 3.13+

See source code

The name of the attribute to be added to the object returned by parse_args().

See source code

A brief description of what the argument does.

See source code

A name for the argument in usage messages.

See source code

Either a name or a list of option strings, e.g. 'foo' or '-f', '--foo'.

See source code

The number of command-line arguments that should be consumed.

See source code

Whether or not the command-line option may be omitted (optionals only).

See source code

The type to which the command-line argument should be converted.

See source code

The version string to be added to the object returned by parse_args().

MUST be used with action='version'.

See https://docs.python.org/3/library/argparse.html#action

See source code

Description for the argument group in help output, by default None

See source code

Title for the argument group in help output; by default “positional arguments” if description is provided, otherwise uses title for positional arguments.

See source code

Add a -h/--help option to the parser (default: True)

See source code

Allows long options to be abbreviated if the abbreviation is unambiguous. (default: True)

See source code

The global default value for arguments (default: None)

See source code

The strategy for resolving conflicting optionals (usually unnecessary)

See source code

Text to display before the argument help (by default, no text)

See source code

Text to display after the argument help (by default, no text)

See source code

Determines whether or not ArgumentParser exits with error info when an error occurs. (default: True)

See source code

A class for customizing the help output

See source code

The set of characters that prefix files from which additional arguments should be read (default: None)

See source code

A list of ArgumentParser objects whose arguments should also be included

See source code

The set of characters that prefix optional arguments (default: ‘-‘)

See source code

The name of the program (default: os.path.basename(sys.argv[0]))

See source code

The string describing the program usage (default: generated from arguments added to parser)

See source code

The basic type of action to be taken when this argument is encountered at the command line.

See source code

Description for the sub-parser group in help output, by default None.

See source code

Name of the attribute under which sub-command name will be stored; by default None and no value is stored.

See source code

Help for sub-parser group in help output, by default None.

See source code

String presenting available subcommands in help; by default it is None and presents subcommands in form {cmd1, cmd2, ..}.

See source code

Class which will be used to create sub-parser instances, by default the class of the current parser (e.g. ArgumentParser).

See source code

Usage information that will be displayed with sub-command help, by default the name of the program and any positional arguments before the subparser argument.

See source code

Whether or not a subcommand must be provided, by default False (added in 3.7)

See source code

Title for the sub-parser group in help output; by default “subcommands” if description is provided, otherwise uses title for positional arguments.

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

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

Unlike regular Django templates, 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 one of the two conditions above.

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

Raises RuntimeError if accessed outside of rendering execution.

Example:

class MyComponent(Component):
    def get_context_data(self):
        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

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.

A single render ID has a chance of collision 1 in 3.3M. However, due to birthday paradox, the chance of collision increases when approaching ~1,000 render IDs.

Thus, there is a soft-cap of 1,000 components rendered on a single page.

If you need to more than that, please open an issue on GitHub.

Example:

class MyComponent(Component):
    def get_context_data(self):
        print(f"Rendering '{self.id}'")
        return {}

MyComponent.render()
# Rendering 'ab3c4d'

See source code

Input holds the data (like arg, kwargs, slots) that were passed to the current execution of the render method.

Raises RuntimeError if accessed outside of rendering execution.

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_context_data(self):
        user_id = self.request.GET['user_id']
        return {
            'user_id': user_id,
        }

See source code

This allows to configure what class is used to generate response from render_to_response

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_context_data(self):
        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_context_data(self):
        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

argparse arguments for the command

See source code

The function that is called when the command is run. If None, the command will print the help message.

See source code

The help text for the command

See source code

The name of the command - this is what is used to call the command

See source code

The input to use when creating the ArgumentParser for this command. If None, the default values will be used.

See source code

Subcommands for the command

See source code

The input to use when this command is a subcommand installed with add_subparser(). If None, the default values 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_context_data(self):
        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_context_data(self):
        return {
            "my_extension": self.my_extension.do_something(),
        }

See source code

The python import path for the module. E.g. app.components.mycomp

See source code

The filesystem path to the module. E.g. /path/to/project/app/components/mycomp.py

See source code

CSS files associated with a Component.

• If a string, it's assumed to be a path to a CSS file.

• If a list, each entry is assumed to be a path to a CSS file.

• If a dict, the keys are media types (e.g. "all", "print", "screen", etc.), and the values are either:

  • A string, assumed to be a path to a CSS file.
  • A list, each entry is assumed to be a path to a CSS file.

Each entry can be a string, bytes, SafeString, PathLike, or a callable that returns one of the former (see ComponentMediaInputPath).

Examples:

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

class MyComponent(Component):
    class Media:
        css = ["path/to/style1.css", "path/to/style2.css"]

class MyComponent(Component):
    class Media:
        css = {
            "all": "path/to/style.css",
            "print": "path/to/print.css",
        }

class MyComponent(Component):
    class Media:
        css = {
            "all": ["path/to/style1.css", "path/to/style2.css"],
            "print": "path/to/print.css",
        }

See source code

Configures whether the component should inherit the media files from the parent component.

• If True, the component inherits the media files from the parent component.
• If False, the component does not inherit the media files from the parent component.
• If a list of components classes, the component inherits the media files ONLY from these specified components.

Read more in Controlling Media Inheritance section.

Example:

Disable media inheritance:

class ParentComponent(Component):
    class Media:
        js = ["parent.js"]

class MyComponent(ParentComponent):
    class Media:
        extend = False  # Don't inherit parent media
        js = ["script.js"]

print(MyComponent.media._js)  # ["script.js"]

Specify which components to inherit from. In this case, the media files are inherited ONLY from the specified components, and NOT from the original parent components:

class ParentComponent(Component):
    class Media:
        js = ["parent.js"]

class MyComponent(ParentComponent):
    class Media:
        # Only inherit from these, ignoring the files from the parent
        extend = [OtherComponent1, OtherComponent2]

        js = ["script.js"]

print(MyComponent.media._js)  # ["script.js", "other1.js", "other2.js"]

See source code

JS files associated with a Component.

• If a string, it's assumed to be a path to a JS file.

• If a list, each entry is assumed to be a path to a JS file.

Each entry can be a string, bytes, SafeString, PathLike, or a callable that returns one of the former (see ComponentMediaInputPath).

Examples:

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

class MyComponent(Component):
    class Media:
        js = ["path/to/script1.js", "path/to/script2.js"]

class MyComponent(Component):
    class Media:
        js = lambda: ["path/to/script1.js", "path/to/script2.js"]