You can publish and share your components for others to use. Here are the steps to do so:
Create a Django project with a similar structure:
project/
+ Authoring component libraries - Django-Components Authoring component libraries
You can publish and share your components for others to use. Here are the steps to do so:
Writing component libraries¤
-
Create a Django project with a similar structure:
project/
|-- myapp/
|-- __init__.py
|-- apps.py
diff --git a/dev/concepts/advanced/component_registry/index.html b/dev/concepts/advanced/component_registry/index.html
index ced5cf08..06a93768 100644
--- a/dev/concepts/advanced/component_registry/index.html
+++ b/dev/concepts/advanced/component_registry/index.html
@@ -1,4 +1,4 @@
- Registering components - Django-Components Registering components
In previous examples you could repeatedly see us using @register() to "register" the components. In this section we dive deeper into what it actually means and how you can manage (add or remove) components.
As a reminder, we may have a component like this:
from django_components import Component, register
+ Registering components - Django-Components Registering components
In previous examples you could repeatedly see us using @register() to "register" the components. In this section we dive deeper into what it actually means and how you can manage (add or remove) components.
As a reminder, we may have a component like this:
from django_components import Component, register
@register("calendar")
class Calendar(Component):
diff --git a/dev/concepts/advanced/hooks/index.html b/dev/concepts/advanced/hooks/index.html
index 5bb0ea89..b57b35b5 100644
--- a/dev/concepts/advanced/hooks/index.html
+++ b/dev/concepts/advanced/hooks/index.html
@@ -1,4 +1,4 @@
- Lifecycle hooks - Django-Components Lifecycle hooks
New in version 0.96
Component hooks are functions that allow you to intercept the rendering process at specific positions.
Available hooks¤
on_render_before
def on_render_before(
+ Lifecycle hooks - Django-Components Lifecycle hooks
New in version 0.96
Component hooks are functions that allow you to intercept the rendering process at specific positions.
Available hooks¤
on_render_before
def on_render_before(
self: Component,
context: Context,
template: Template
diff --git a/dev/concepts/advanced/html_tragments/index.html b/dev/concepts/advanced/html_tragments/index.html
index fefdfe78..f2d58495 100644
--- a/dev/concepts/advanced/html_tragments/index.html
+++ b/dev/concepts/advanced/html_tragments/index.html
@@ -1,4 +1,4 @@
- HTML fragments - Django-Components HTML fragments
Django-components provides a seamless integration with HTML fragments (HTML over the wire), whether you're using HTMX, AlpineJS, or vanilla JavaScript.
When you define a component that has extra JS or CSS, and you use django-components to render the fragment, django-components will:
- Automatically load the associated JS and CSS
- Ensure that JS is loaded and executed only once even if the fragment is inserted multiple times
Info
What are HTML fragments and "HTML over the wire"?
It is one of the methods for updating the state in the browser UI upon user interaction.
How it works is that:
- User makes an action - clicks a button or submits a form
- The action causes a request to be made from the client to the server.
- Server processes the request (e.g. form submission), and responds with HTML of some part of the UI (e.g. a new entry in a table).
- A library like HTMX, AlpineJS, or custom function inserts the new HTML into the correct place.
Document and fragment types¤
Components support two modes of rendering - As a "document" or as a "fragment".
What's the difference?
Document mode¤
Document mode assumes that the rendered components will be embedded into the HTML of the initial page load. This means that:
- The JS and CSS is embedded into the HTML as
<script> and <style> tags (see JS and CSS output locations) - Django-components injects a JS script for managing JS and CSS assets
A component is rendered as a "document" when:
- It is embedded inside a template as
{% component %} - It is rendered with
Component.render() or Component.render_to_response() with the type kwarg set to "document" (default)
Example:
MyTable.render(
+ HTML fragments - Django-Components HTML fragments
Django-components provides a seamless integration with HTML fragments (HTML over the wire), whether you're using HTMX, AlpineJS, or vanilla JavaScript.
When you define a component that has extra JS or CSS, and you use django-components to render the fragment, django-components will:
- Automatically load the associated JS and CSS
- Ensure that JS is loaded and executed only once even if the fragment is inserted multiple times
Info
What are HTML fragments and "HTML over the wire"?
It is one of the methods for updating the state in the browser UI upon user interaction.
How it works is that:
- User makes an action - clicks a button or submits a form
- The action causes a request to be made from the client to the server.
- Server processes the request (e.g. form submission), and responds with HTML of some part of the UI (e.g. a new entry in a table).
- A library like HTMX, AlpineJS, or custom function inserts the new HTML into the correct place.
Document and fragment types¤
Components support two modes of rendering - As a "document" or as a "fragment".
What's the difference?
Document mode¤
Document mode assumes that the rendered components will be embedded into the HTML of the initial page load. This means that:
- The JS and CSS is embedded into the HTML as
<script> and <style> tags (see JS and CSS output locations) - Django-components injects a JS script for managing JS and CSS assets
A component is rendered as a "document" when:
- It is embedded inside a template as
{% component %} - It is rendered with
Component.render() or Component.render_to_response() with the type kwarg set to "document" (default)
Example:
MyTable.render(
kwargs={...},
)
diff --git a/dev/concepts/advanced/provide_inject/index.html b/dev/concepts/advanced/provide_inject/index.html
index 5065f30d..af282edb 100644
--- a/dev/concepts/advanced/provide_inject/index.html
+++ b/dev/concepts/advanced/provide_inject/index.html
@@ -1,4 +1,4 @@
- Prop drilling and provide / inject - Django-Components Prop drilling and provide / inject
New in version 0.80:
Django components supports the provide / inject or ContextProvider pattern with the combination of:
{% provide %} taginject() method of the Component class
What is "prop drilling"?¤
Prop drilling refers to a scenario in UI development where you need to pass data through many layers of a component tree to reach the nested components that actually need the data.
Normally, you'd use props to send data from a parent component to its children. However, this straightforward method becomes cumbersome and inefficient if the data has to travel through many levels or if several components scattered at different depths all need the same piece of information.
This results in a situation where the intermediate components, which don't need the data for their own functioning, end up having to manage and pass along these props. This clutters the component tree and makes the code verbose and harder to manage.
A neat solution to avoid prop drilling is using the "provide and inject" technique.
With provide / inject, a parent component acts like a data hub for all its descendants. This setup allows any component, no matter how deeply nested it is, to access the required data directly from this centralized provider without having to messily pass props down the chain. This approach significantly cleans up the code and makes it easier to maintain.
This feature is inspired by Vue's Provide / Inject and React's Context / useContext.
How to use provide / inject¤
As the name suggest, using provide / inject consists of 2 steps
- Providing data
- Injecting provided data
For examples of advanced uses of provide / inject, see this discussion.
Using {% provide %} tag¤
First we use the {% provide %} tag to define the data we want to "provide" (make available).
{% provide "my_data" key="hi" another=123 %}
+ Prop drilling and provide / inject - Django-Components Prop drilling and provide / inject
New in version 0.80:
Django components supports the provide / inject or ContextProvider pattern with the combination of:
{% provide %} taginject() method of the Component class
What is "prop drilling"?¤
Prop drilling refers to a scenario in UI development where you need to pass data through many layers of a component tree to reach the nested components that actually need the data.
Normally, you'd use props to send data from a parent component to its children. However, this straightforward method becomes cumbersome and inefficient if the data has to travel through many levels or if several components scattered at different depths all need the same piece of information.
This results in a situation where the intermediate components, which don't need the data for their own functioning, end up having to manage and pass along these props. This clutters the component tree and makes the code verbose and harder to manage.
A neat solution to avoid prop drilling is using the "provide and inject" technique.
With provide / inject, a parent component acts like a data hub for all its descendants. This setup allows any component, no matter how deeply nested it is, to access the required data directly from this centralized provider without having to messily pass props down the chain. This approach significantly cleans up the code and makes it easier to maintain.
This feature is inspired by Vue's Provide / Inject and React's Context / useContext.
How to use provide / inject¤
As the name suggest, using provide / inject consists of 2 steps
- Providing data
- Injecting provided data
For examples of advanced uses of provide / inject, see this discussion.
Using {% provide %} tag¤
First we use the {% provide %} tag to define the data we want to "provide" (make available).
{% provide "my_data" key="hi" another=123 %}
{% component "child" / %} <--- Can access "my_data"
{% endprovide %}
diff --git a/dev/concepts/advanced/rendering_js_css/index.html b/dev/concepts/advanced/rendering_js_css/index.html
index cfa45c92..ff5c1765 100644
--- a/dev/concepts/advanced/rendering_js_css/index.html
+++ b/dev/concepts/advanced/rendering_js_css/index.html
@@ -1,4 +1,4 @@
- Rendering JS / CSS - Django-Components Rendering JS / CSS
JS and CSS output locations¤
If:
- Your components use JS and CSS via any of:
- And you use the
ComponentDependencyMiddleware middleware
Then, by default, the components' JS and CSS will be automatically inserted into the HTML:
- CSS styles will be inserted at the end of the
<head> - JS scripts will be inserted at the end of the
<body>
If you want to place the dependencies elsewhere in the HTML, you can override the locations by inserting following Django template tags:
{% component_js_dependencies %} - Set new location(s) for JS scripts{% component_css_dependencies %} - Set new location(s) for CSS styles
So if you have a component with JS and CSS:
from django_components import Component, types
+ Rendering JS / CSS - Django-Components Rendering JS / CSS
JS and CSS output locations¤
If:
- Your components use JS and CSS via any of:
- And you use the
ComponentDependencyMiddleware middleware
Then, by default, the components' JS and CSS will be automatically inserted into the HTML:
- CSS styles will be inserted at the end of the
<head> - JS scripts will be inserted at the end of the
<body>
If you want to place the dependencies elsewhere in the HTML, you can override the locations by inserting following Django template tags:
{% component_js_dependencies %} - Set new location(s) for JS scripts{% component_css_dependencies %} - Set new location(s) for CSS styles
So if you have a component with JS and CSS:
from django_components import Component, types
class MyButton(Component):
template: types.django_html = """
diff --git a/dev/concepts/advanced/tag_formatter/index.html b/dev/concepts/advanced/tag_formatter/index.html
index cd1c44aa..0302b833 100644
--- a/dev/concepts/advanced/tag_formatter/index.html
+++ b/dev/concepts/advanced/tag_formatter/index.html
@@ -1,4 +1,4 @@
- Tag formatters - Django-Components Tag formatters
Customizing component tags with TagFormatter¤
New in version 0.89
By default, components are rendered using the pair of {% component %} / {% endcomponent %} template tags:
{% component "button" href="..." disabled %}
+ Tag formatters - Django-Components Tag formatters
Customizing component tags with TagFormatter¤
New in version 0.89
By default, components are rendered using the pair of {% component %} / {% endcomponent %} template tags:
{% component "button" href="..." disabled %}
Click me!
{% endcomponent %}
diff --git a/dev/concepts/advanced/typing_and_validation/index.html b/dev/concepts/advanced/typing_and_validation/index.html
index 50395d73..d05d3f80 100644
--- a/dev/concepts/advanced/typing_and_validation/index.html
+++ b/dev/concepts/advanced/typing_and_validation/index.html
@@ -1,4 +1,4 @@
- Typing and validation - Django-Components Typing and validation
Adding type hints with Generics¤
New in version 0.92
The Component class optionally accepts type parameters that allow you to specify the types of args, kwargs, slots, and data:
class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
+ Typing and validation - Django-Components Typing and validation
Adding type hints with Generics¤
New in version 0.92
The Component class optionally accepts type parameters that allow you to specify the types of args, kwargs, slots, and data:
Args - Must be a Tuple or AnyKwargs - Must be a TypedDict or AnyData - Must be a TypedDict or AnySlots - Must be a TypedDict or Any
Here's a full example:
from typing import NotRequired, Tuple, TypedDict, SlotContent, SlotFunc
diff --git a/dev/concepts/fundamentals/access_component_input/index.html b/dev/concepts/fundamentals/access_component_input/index.html
index 0cc91d46..6573e9c4 100644
--- a/dev/concepts/fundamentals/access_component_input/index.html
+++ b/dev/concepts/fundamentals/access_component_input/index.html
@@ -1,4 +1,4 @@
- Accessing component inputs - Django-Components Accessing component inputs
When you call Component.render or Component.render_to_response, the inputs to these methods can be accessed from within the instance under self.input.
This means that you can use self.input inside:
get_context_dataget_template_nameget_templateon_render_beforeon_render_after
self.input is only defined during the execution of Component.render, and raises a RuntimeError when called outside of this context.
self.input has the same fields as the input to Component.render:
class TestComponent(Component):
+ Accessing component inputs - Django-Components Accessing component inputs
When you call Component.render or Component.render_to_response, the inputs to these methods can be accessed from within the instance under self.input.
This means that you can use self.input inside:
get_context_dataget_template_nameget_templateon_render_beforeon_render_after
self.input is only defined during the execution of Component.render, and raises a RuntimeError when called outside of this context.
self.input has the same fields as the input to Component.render:
class TestComponent(Component):
def get_context_data(self, var1, var2, variable, another, **attrs):
assert self.input.args == (123, "str")
assert self.input.kwargs == {"variable": "test", "another": 1}
diff --git a/dev/concepts/fundamentals/autodiscovery/index.html b/dev/concepts/fundamentals/autodiscovery/index.html
index 3b806446..c2e4d561 100644
--- a/dev/concepts/fundamentals/autodiscovery/index.html
+++ b/dev/concepts/fundamentals/autodiscovery/index.html
@@ -1,4 +1,4 @@
- Autodiscovery - Django-Components Autodiscovery
Every component that you want to use in the template with the {% component %} tag needs to be registered with the ComponentRegistry. Normally, we use the @register decorator for that:
from django_components import Component, register
+ Autodiscovery - Django-Components Autodiscovery
Every component that you want to use in the template with the {% component %} tag needs to be registered with the ComponentRegistry. Normally, we use the @register decorator for that:
from django_components import Component, register
@register("calendar")
class Calendar(Component):
diff --git a/dev/concepts/fundamentals/component_context_scope/index.html b/dev/concepts/fundamentals/component_context_scope/index.html
index 8d9b06af..fec63d9d 100644
--- a/dev/concepts/fundamentals/component_context_scope/index.html
+++ b/dev/concepts/fundamentals/component_context_scope/index.html
@@ -1,4 +1,4 @@
- Component context and scope - Django-Components Component context and scope
By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
With this in mind, the {% component %} tag behaves similarly to {% include %} tag - inside the component tag, you can access all variables that were defined outside of it.
And just like with {% include %}, if you don't want a specific component template to have access to the parent context, add only to the {% component %} tag:
{% component "calendar" date="2015-06-19" only / %}
+ Component context and scope - Django-Components Component context and scope
By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
With this in mind, the {% component %} tag behaves similarly to {% include %} tag - inside the component tag, you can access all variables that were defined outside of it.
And just like with {% include %}, if you don't want a specific component template to have access to the parent context, add only to the {% component %} tag:
NOTE: {% csrf_token %} tags need access to the top-level context, and they will not function properly if they are rendered in a component that is called with the only modifier.
If you find yourself using the only modifier often, you can set the context_behavior option to "isolated", which automatically applies the only modifier. This is useful if you want to make sure that components don't accidentally access the outer context.
Components can also access the outer context in their context methods like get_context_data by accessing the property self.outer_context.
Example of Accessing Outer Context¤
<div>
{% component "calender" / %}
</div>
diff --git a/dev/concepts/fundamentals/components_as_views/index.html b/dev/concepts/fundamentals/components_as_views/index.html
index 02eb0922..a02be55a 100644
--- a/dev/concepts/fundamentals/components_as_views/index.html
+++ b/dev/concepts/fundamentals/components_as_views/index.html
@@ -1,4 +1,4 @@
- Components as views - Django-Components Components as views
New in version 0.34
Note: Since 0.92, Component no longer subclasses View. To configure the View class, set the nested Component.View class
Components can now be used as views:
-
Components define the Component.as_view() class method that can be used the same as View.as_view().
-
By default, you can define GET, POST or other HTTP handlers directly on the Component, same as you do with View. For example, you can override get and post to handle GET and POST requests, respectively.
-
In addition, Component now has a render_to_response method that renders the component template based on the provided context and slots' data and returns an HttpResponse object.
Component as view example¤
Here's an example of a calendar component defined as a view:
# In a file called [project root]/components/calendar.py
+ Components as views - Django-Components Components as views
New in version 0.34
Note: Since 0.92, Component no longer subclasses View. To configure the View class, set the nested Component.View class
Components can now be used as views:
-
Components define the Component.as_view() class method that can be used the same as View.as_view().
-
By default, you can define GET, POST or other HTTP handlers directly on the Component, same as you do with View. For example, you can override get and post to handle GET and POST requests, respectively.
-
In addition, Component now has a render_to_response method that renders the component template based on the provided context and slots' data and returns an HttpResponse object.
Component as view example¤
Here's an example of a calendar component defined as a view:
# In a file called [project root]/components/calendar.py
from django_components import Component, ComponentView, register
@register("calendar")
diff --git a/dev/concepts/fundamentals/components_in_python/index.html b/dev/concepts/fundamentals/components_in_python/index.html
index c9cadd2e..22067633 100644
--- a/dev/concepts/fundamentals/components_in_python/index.html
+++ b/dev/concepts/fundamentals/components_in_python/index.html
@@ -1,4 +1,4 @@
- Components in Python - Django-Components Components in Python
New in version 0.81
Components can be rendered outside of Django templates, calling them as regular functions ("React-style").
The component class defines render and render_to_response class methods. These methods accept positional args, kwargs, and slots, offering the same flexibility as the {% component %} tag:
class SimpleComponent(Component):
+ Components in Python - Django-Components Components in Python
New in version 0.81
Components can be rendered outside of Django templates, calling them as regular functions ("React-style").
The component class defines render and render_to_response class methods. These methods accept positional args, kwargs, and slots, offering the same flexibility as the {% component %} tag:
class SimpleComponent(Component):
template = """
{% load component_tags %}
hello: {{ hello }}
diff --git a/dev/concepts/fundamentals/defining_js_css_html_files/index.html b/dev/concepts/fundamentals/defining_js_css_html_files/index.html
index 805ef11d..121e7b94 100644
--- a/dev/concepts/fundamentals/defining_js_css_html_files/index.html
+++ b/dev/concepts/fundamentals/defining_js_css_html_files/index.html
@@ -1,4 +1,4 @@
- Defining HTML / JS / CSS files - Django-Components Defining HTML / JS / CSS files
As you could have seen in the tutorial, there's multiple ways how you can associate HTML / JS / CSS with a component:
- You can set
Component.template, Component.css and Component.js to define the main HTML / CSS / JS for a component as inlined code. - You can set
Component.template_name, Component.css_file and Component.js_file to define the main HTML / CSS / JS for a component in separate files. - You can link additional CSS / JS files using
Component.Media.js and Component.Media.css.
Warning
You cannot use both inlined code and separate file for a single language type:
- You can only either set
Component.template or Component.template_name - You can only either set
Component.css or Component.css_file - You can only either set
Component.js or Component.js_file
However, you can freely mix these for different languages:
class MyTable(Component):
+ Defining HTML / JS / CSS files - Django-Components Defining HTML / JS / CSS files
As you could have seen in the tutorial, there's multiple ways how you can associate HTML / JS / CSS with a component:
- You can set
Component.template, Component.css and Component.js to define the main HTML / CSS / JS for a component as inlined code. - You can set
Component.template_name, Component.css_file and Component.js_file to define the main HTML / CSS / JS for a component in separate files. - You can link additional CSS / JS files using
Component.Media.js and Component.Media.css.
Warning
You cannot use both inlined code and separate file for a single language type:
- You can only either set
Component.template or Component.template_name - You can only either set
Component.css or Component.css_file - You can only either set
Component.js or Component.js_file
However, you can freely mix these for different languages:
class MyTable(Component):
template: types.django_html = """
<div class="welcome">
Hi there!
diff --git a/dev/concepts/fundamentals/html_attributes/index.html b/dev/concepts/fundamentals/html_attributes/index.html
index 19e03f17..210089a5 100644
--- a/dev/concepts/fundamentals/html_attributes/index.html
+++ b/dev/concepts/fundamentals/html_attributes/index.html
@@ -1,4 +1,4 @@
- HTML attributes - Django-Components