Settings

extensions: Sequence[type[ComponentExtension] | str] | None

List of extensions to be loaded.

The extensions can be specified as:

• Python import path, e.g. "path.to.my_extension.MyExtension".
• Extension class, e.g. my_extension.MyExtension.

Read more about extensions.

COMPONENTS = ComponentsSettings(
    extensions=[
        "path.to.my_extension.MyExtension",
        StorybookExtension,
    ],
)

extensions_defaults: dict[str, Any] | None

Global defaults for the extension classes.

Read more about Extension defaults.

COMPONENTS = ComponentsSettings(
    extensions_defaults={
        "my_extension": {
            "my_setting": "my_value",
        },
        "cache": {
            "enabled": True,
            "ttl": 60,
        },
    },
)

autodiscover: bool | None

Toggle whether to run autodiscovery at the Django server startup.

Defaults to True

COMPONENTS = ComponentsSettings(
    autodiscover=False,
)

dirs: Sequence[str | PathLike | tuple[str, str] | tuple[str, PathLike]] | None

Specify the directories that contain your components.

Defaults to [Path(settings.BASE_DIR) / "components"]. That is, the root components/ app.

Directories must be full paths, same as with STATICFILES_DIRS.

These locations are searched during autodiscovery, or when you define HTML, JS, or CSS as separate files.

COMPONENTS = ComponentsSettings(
    dirs=[BASE_DIR / "components"],
)

Set to empty list to disable global components directories:

COMPONENTS = ComponentsSettings(
    dirs=[],
)

app_dirs: Sequence[str] | None

Specify the app-level directories that contain your components.

Defaults to ["components"]. That is, for each Django app, we search <app>/components/ for components.

The paths must be relative to app, e.g.:

COMPONENTS = ComponentsSettings(
    app_dirs=["my_comps"],
)

To search for <app>/my_comps/.

These locations are searched during autodiscovery, or when you define HTML, JS, or CSS as separate files.

Set to empty list to disable app-level components:

COMPONENTS = ComponentsSettings(
    app_dirs=[],
)

cache: str | None

Name of the Django cache to be used for storing component's JS and CSS files.

If None, a LocMemCache is used with default settings.

Defaults to None.

Read more about caching.

COMPONENTS = ComponentsSettings(
    cache="my_cache",
)

context_behavior: ContextBehaviorType | None

Configure whether, inside a component template, you can use variables from the outside ("django") or not ("isolated"). This also affects what variables are available inside the {% fill %} tags.

Also see Component context and scope.

Defaults to "django".

COMPONENTS = ComponentsSettings(
    context_behavior="isolated",
)

NOTE: context_behavior and slot_context_behavior options were merged in v0.70.

If you are migrating from BEFORE v0.67, set context_behavior to "django". From v0.67 to v0.78 (incl) the default value was "isolated".

For v0.79 and later, the default is again "django". See the rationale for this change.

debug_highlight_components: bool | None

DEPRECATED. Use extensions_defaults instead. Will be removed in v1.

Enable / disable component highlighting. See Troubleshooting for more details.

Defaults to False.

COMPONENTS = ComponentsSettings(
    debug_highlight_components=True,
)

debug_highlight_slots: bool | None

DEPRECATED. Use extensions_defaults instead. Will be removed in v1.

Enable / disable slot highlighting. See Troubleshooting for more details.

Defaults to False.

COMPONENTS = ComponentsSettings(
    debug_highlight_slots=True,
)

dynamic_component_name: str | None

By default, the dynamic component is registered under the name "dynamic".

In case of a conflict, you can use this setting to change the component name used for the dynamic components.

# settings.py
COMPONENTS = ComponentsSettings(
    dynamic_component_name="my_dynamic",
)

After which you will be able to use the dynamic component with the new name:

{% component "my_dynamic" is=table_comp data=table_data headers=table_headers %}
    {% fill "pagination" %}
        {% component "pagination" / %}
    {% endfill %}
{% endcomponent %}

libraries: list[str] | None

Configure extra python modules that should be loaded.

This may be useful if you are not using the autodiscovery feature, or you need to load components from non-standard locations. Thus you can have a structure of components that is independent from your apps.

Expects a list of python module paths. Defaults to empty list.

COMPONENTS = ComponentsSettings(
    libraries=[
        "mysite.components.forms",
        "mysite.components.buttons",
        "mysite.components.cards",
    ],
)

class MyAppConfig(AppConfig):
    def ready(self):
        import "mysite.components.forms"
        import "mysite.components.buttons"
        import "mysite.components.cards"

Manually loading libraries

In the rare case that you need to manually trigger the import of libraries, you can use the import_libraries() function:

from django_components import import_libraries

import_libraries()

multiline_tags: bool | None

Enable / disable multiline support for template tags. If True, template tags like {% component %} or {{ my_var }} can span multiple lines.

Defaults to True.

Disable this setting if you are making custom modifications to Django's regular expression for parsing templates at django.template.base.tag_re.

COMPONENTS = ComponentsSettings(
    multiline_tags=False,
)

reload_on_template_change: bool | None

Deprecated. Use COMPONENTS.reload_on_file_change instead.

reload_on_file_change: bool | ReloadModeType | None

Configure how django_components reacts when component files (HTML templates, JS, CSS) change on disk while the dev server is running.

See Hot-reloading component files during development.

Options:

• False or "off" - No file watching. Changes are not picked up until the server is manually restarted.
• True or "hot" - Clear the in-memory component cache so the next render reads fresh content from disk. The dev server keeps running without a restart.
• "restart" - Same as "hot", but also triggers a full dev server restart. Deprecated, will be removed in v1.

Defaults to "hot".

static_files_allowed: list[str | Pattern] | None

A list of file extensions (including the leading dot) that define which files within COMPONENTS.dirs or COMPONENTS.app_dirs are treated as static files.

If a file is matched against any of the patterns, it's considered a static file. Such files are collected when running collectstatic, and can be accessed under the static file endpoint.

You can also pass in compiled regexes (re.Pattern) for more advanced patterns.

By default, JS, CSS, and common image and font file formats are considered static files:

COMPONENTS = ComponentsSettings(
    static_files_allowed=[
        ".css",
        ".js", ".jsx", ".ts", ".tsx",
        # Images
        ".apng", ".png", ".avif", ".gif", ".jpg",
        ".jpeg",  ".jfif", ".pjpeg", ".pjp", ".svg",
        ".webp", ".bmp", ".ico", ".cur", ".tif", ".tiff",
        # Fonts
        ".eot", ".ttf", ".woff", ".otf", ".svg",
    ],
)

forbidden_static_files: list[str | Pattern] | None

Deprecated. Use COMPONENTS.static_files_forbidden instead.

static_files_forbidden: list[str | Pattern] | None

A list of file extensions (including the leading dot) that define which files within COMPONENTS.dirs or COMPONENTS.app_dirs will NEVER be treated as static files.

If a file is matched against any of the patterns, it will never be considered a static file, even if the file matches a pattern in static_files_allowed.

Use this setting together with static_files_allowed for a fine control over what file types will be exposed.

You can also pass in compiled regexes (re.Pattern) for more advanced patterns.

By default, any HTML and Python are considered NOT static files:

COMPONENTS = ComponentsSettings(
    static_files_forbidden=[
        ".html", ".django", ".dj", ".tpl",
        # Python files
        ".py", ".pyc",
    ],
)

tag_formatter: TagFormatterABC | str | None

Configure what syntax is used inside Django templates to render components. See the available tag formatters.

Defaults to "django_components.component_formatter".

Learn more about Customizing component tags with TagFormatter.

Can be set either as direct reference:

from django_components import component_formatter

COMPONENTS = ComponentsSettings(
    "tag_formatter": component_formatter
)

Or as an import string;

COMPONENTS = ComponentsSettings(
    "tag_formatter": "django_components.component_formatter"
)

template_cache_size: int | None

DEPRECATED. Template caching will be removed in v1.

Configure the maximum amount of Django templates to be cached.

Defaults to 128.

Each time a Django template is rendered, it is cached to a global in-memory cache (using Python's lru_cache decorator). This speeds up the next render of the component. As the same component is often used many times on the same page, these savings add up.

By default the cache holds 128 component templates in memory, which should be enough for most sites. But if you have a lot of components, or if you are overriding Component.get_template() to render many dynamic templates, you can increase this number.

COMPONENTS = ComponentsSettings(
    template_cache_size=256,
)

To remove the cache limit altogether and cache everything, set template_cache_size to None.

COMPONENTS = ComponentsSettings(
    template_cache_size=None,
)

If you want to add templates to the cache yourself, you can use cached_template():

from django_components import cached_template

cached_template("Variable: {{ variable }}")

# You can optionally specify Template class, and other Template inputs:
class MyTemplate(Template):
    pass

cached_template(
    "Variable: {{ variable }}",
    template_cls=MyTemplate,
    name=...
    origin=...
    engine=...
)