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 0085b385..ba76bf72 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 a880ee70..985669d7 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 15529ea2..0c5ce192 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 47e852a6..b755925b 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 5232e22b..5284f138 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 5414e96f..35b0e0f1 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 39c062bc..d2f3927b 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 67968d1d..2200b2ef 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 a0c728cc..7c2f5394 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 18202845..767ce604 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 22dc1761..27acc657 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 051c9267..c52cef71 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 bc41af5b..8e314aa9 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_file, 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_file - 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_file, 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_file - 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:
Note
django-component's management of files is inspired by Django's Media class.
To be familiar with how Django handles static files, we recommend reading also:
Defining file paths relative to component¤
As seen in the getting started example, to associate HTML / JS / CSS files with a component, you can set them as Component.template_file, Component.js_file and Component.css_file respectively:
Note
django-component's management of files is inspired by Django's Media class.
To be familiar with how Django handles static files, we recommend reading also:
Defining file paths relative to component¤
As seen in the getting started example, to associate HTML / JS / CSS files with a component, you can set them as Component.template_file, Component.js_file and Component.css_file respectively:
[project root]/components/calendar/calendar.pyfrom django_components import Component, register
@register("calendar")
class Calendar(Component):
@@ -154,4 +154,4 @@
# Output:
# <script src="/static/path/to/script.js"></script>
# <link href="/static/path/to/style.css" media="all" rel="stylesheet">
-
If you want to modify the class that is instantiated for Component.media, you can configure Component.media_class (See example).
\ No newline at end of file
+ If you want to modify the class that is instantiated for Component.media, you can configure Component.media_class (See example).
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/html_attributes/index.html b/dev/concepts/fundamentals/html_attributes/index.html
index 9aecc58a..20f837eb 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 HTML attributes
New in version 0.74:
You can use the html_attrs tag to render HTML attributes, given a dictionary of values.
So if you have a template:
<div class="{{ classes }}" data-id="{{ my_id }}">
+ HTML attributes - Django-Components HTML attributes
New in version 0.74:
You can use the html_attrs tag to render HTML attributes, given a dictionary of values.
So if you have a template:
You can simplify it with html_attrs tag:
<div {% html_attrs attrs %}>
</div>
diff --git a/dev/concepts/fundamentals/single_file_components/index.html b/dev/concepts/fundamentals/single_file_components/index.html
index 537ce4e5..4efaae04 100644
--- a/dev/concepts/fundamentals/single_file_components/index.html
+++ b/dev/concepts/fundamentals/single_file_components/index.html
@@ -1,4 +1,4 @@
- Single-file components - Django-Components Single-file components
Components can be defined in a single file, which is useful for small components. To do this, you can use the template, js, and css class attributes instead of the template_file, js_file, and css_file.
For example, here's the calendar component from the Getting started tutorial, defined in a single file:
[project root]/components/calendar.pyfrom django_components import Component, register, types
+ Single-file components - Django-Components Single-file components
Components can be defined in a single file, which is useful for small components. To do this, you can use the template, js, and css class attributes instead of the template_file, js_file, and css_file.
For example, here's the calendar component from the Getting started tutorial, defined in a single file:
[project root]/components/calendar.pyfrom django_components import Component, register, types
@register("calendar")
class Calendar(Component):
@@ -32,4 +32,4 @@
}
})()
"""
-
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
To add syntax highlighting to these snippets, head over to Syntax highlighting.
\ No newline at end of file
+
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
To add syntax highlighting to these snippets, head over to Syntax highlighting.
\ No newline at end of file
diff --git a/dev/concepts/fundamentals/slots/index.html b/dev/concepts/fundamentals/slots/index.html
index 117a2c68..63315895 100644
--- a/dev/concepts/fundamentals/slots/index.html
+++ b/dev/concepts/fundamentals/slots/index.html
@@ -1,4 +1,4 @@
- Slots - Django-Components Slots
New in version 0.26:
- The
slot tag now serves only to declare new slots inside the component template. - To override the content of a declared slot, use the newly introduced
fill tag instead. - Whereas unfilled slots used to raise a warning, filling a slot is now optional by default.
- To indicate that a slot must be filled, the new
required option should be added at the end of the slot tag.
Components support something called 'slots'. When a component is used inside another template, slots allow the parent template to override specific parts of the child component by passing in different content. This mechanism makes components more reusable and composable. This behavior is similar to slots in Vue.
In the example below we introduce two block tags that work hand in hand to make this work. These are...
{% slot <name> %}/{% endslot %}: Declares a new slot in the component template.{% fill <name> %}/{% endfill %}: (Used inside a {% component %} tag pair.) Fills a declared slot with the specified content.
Let's update our calendar component to support more customization. We'll add slot tag pairs to its template, template.html.