django-components/docs/reference/settings.md

<!-- Autogenerated by reference.py -->

# Settings

You can configure django_components with a global `COMPONENTS` variable in your Django settings file, e.g. `settings.py`.
By default you don't need it set, there are resonable [defaults](#settings-defaults).

To configure the settings you can instantiate [`ComponentsSettings`](../api#django_components.ComponentsSettings)
for validation and type hints. Or, for backwards compatibility, you can also use plain dictionary:

```python
# settings.py
from django_components import ComponentsSettings

COMPONENTS = ComponentsSettings(
    autodiscover=True,
    ...
)

# or

COMPONENTS = {
    "autodiscover": True,
    ...
}
```


### Settings defaults

Here's overview of all available settings and their defaults:

```py
defaults = ComponentsSettings(
    autodiscover=True,
    context_behavior=ContextBehavior.DJANGO.value,  # "django" | "isolated"
    # Root-level "components" dirs, e.g. `/path/to/proj/components/`
    dirs=[Path(settings.BASE_DIR) / "components"],
    # App-level "components" dirs, e.g. `[app]/components/`
    app_dirs=["components"],
    dynamic_component_name="dynamic",
    libraries=[],  # E.g. ["mysite.components.forms", ...]
    multiline_tags=True,
    reload_on_file_change=False,
    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",
    ],
    static_files_forbidden=[
        # See https://marketplace.visualstudio.com/items?itemName=junstyle.vscode-django-support
        ".html", ".django", ".dj", ".tpl",
        # Python files
        ".py", ".pyc",
    ],
    tag_formatter="django_components.component_formatter",
    template_cache_size=128,
)
```

::: django_components.app_settings.ComponentsSettings.app_dirs
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.autodiscover
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.context_behavior
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.dirs
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.dynamic_component_name
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.forbidden_static_files
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.libraries
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.multiline_tags
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.reload_on_file_change
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.reload_on_template_change
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.static_files_allowed
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.static_files_forbidden
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.tag_formatter
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false

::: django_components.app_settings.ComponentsSettings.template_cache_size
    options:
      show_root_heading: true
      show_signature: true
      separate_signature: true
      show_symbol_type_heading: false
      show_symbol_type_toc: false
      show_if_no_docstring: true
      show_labels: false