Skip to content

Your First Component

Overview

Components are one of the core concepts of ReactPy. They are the foundation upon which you build user interfaces (UI), which makes them the perfect place to start your journey!

Note

If you have reached this point, you should have already installed ReactPy-Django through the previous steps.

Selecting a Django App

You will now need to pick at least one Django app to start using ReactPy-Django on.

For the following examples, we will assume the following:

  1. You have a Django app named my_app, which was created by Django's startapp command.
  2. You have placed my_app directly into your Django project folder (./example_project/my_app). This is common for small projects.
How do I organize my Django project for ReactPy?

ReactPy-Django has no project structure requirements. Organize everything as you wish, just like any Django project.

Defining a component

You will need a file to start creating ReactPy components.

We recommend creating a components.py file within your chosen Django app to start out. For this example, the file path will look like this: ./example_project/my_app/components.py.

Within this file, you will define your component function(s) using the @component decorator.

1
2
3
4
5
from reactpy import component, html

@component
def hello_world(recipient: str):
    return html.h1(f"Hello {recipient}!")
What should I name my ReactPy files and functions?

You have full freedom in naming/placement of your files and functions.

We recommend creating a components.py for small Django apps. If your app has a lot of components, you should consider breaking them apart into individual modules such as components/navbar.py.

Ultimately, components are referenced by Python dotted path in my_template.html (see next step). This dotted path must be valid to Python's importlib.

What does the decorator actually do?

While not all components need to be decorated, there are a few features this decorator adds to your components.

  1. The ability to be used as a root component.
    • The decorator is required for any component that you want to reference in your Django templates (see next step).
  2. The ability to use hooks.
    • The decorator is required on any component where hooks are defined.
  3. Scoped failures.
    • If a decorated component generates an exception, then only that one component will fail to render.

Embedding in a template

In your Django app's HTML template, you can now embed your ReactPy component using the {% component %} template tag. Within this tag, you will need to type in the dotted path to the component.

Additionally, you can pass in args and kwargs into your component function. After reading the code below, pay attention to how the function definition for hello_world (from the previous step) accepts a recipient argument.

1
2
3
4
5
6
7
{% load reactpy %}
<!DOCTYPE html>
<html>
  <body>
    {% component "example_project.my_app.components.hello_world" recipient="World" %}
  </body>
</html>
Components are automatically registered!

ReactPy-Django will automatically register any component that is referenced in a Django HTML template. This means you typically do not need to manually register components in your Django app.

Please note that this HTML template must be properly stored within a registered Django app. ReactPy-Django will output a console log message containing all detected components when the server starts up.

Do not use context variables for the component path

The ReactPy component finder requires that your component path is a string.

Do not use Django template/context variables for the component path. Failure to follow this warning will result in render failures.

For example, do not do the following:

1
2
3
4
5
<!-- This is good -->
{% component "example_project.my_app.components.hello_world" recipient="World" %}

<!-- This is bad -->
{% component my_variable recipient="World" %}

1
2
3
4
5
6
7
8
9
from django.shortcuts import render


def example_view(request):
    return render(
        request,
        "my_template.html",
        context={"my_variable": "example_project.my_app.components.hello_world"},
    )

Note: If you decide to not follow this warning, you will need to use the register_component function to manually register your components.

Can I use multiple components on one page?

You can add as many components to a webpage as needed by using the template tag multiple times. Retrofitting legacy sites to use ReactPy will typically involve many components on one page.

1
2
3
4
5
6
7
8
9
{% load reactpy %}
<!DOCTYPE html>
<html>
    <body>
        <h1>{% component "example_project.my_app.components.my_title" %}</h1>
        <p>{% component "example_project.my_app_2.components.goodbye_world" class="bold small-font" %}</p>
        {% component "example_project.my_app_3.components.my_button" %}
    </body>
</html>

Please note that components separated like this will not be able to interact with each other, except through database queries.

Additionally, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one component within your <body> tag.

Where is my templates folder?

If you do not have a ./templates/ folder in your Django app, you can simply create one! Keep in mind, templates within this folder will not be detected by Django unless you add the corresponding Django app to settings.py:INSTALLED_APPS.

Setting up a Django view

Within your Django app's views.py file, you will need to create a view function to render the HTML template my_template.html (from the previous step).

1
2
3
4
5
from django.shortcuts import render


def index(request):
    return render(request, "my_template.html")

We will add this new view into your urls.py and define what URL it should be accessible at.

1
2
3
4
5
6
7
from django.urls import path

from example import views

urlpatterns = [
    path("example/", views.index),
]
Which urls.py do I add my views to?

For simple Django projects, you can easily add all of your views directly into the Django project's urls.py. However, as you start increase your project's complexity you might end up with way too much within one file.

Once you reach that point, we recommend creating an individual urls.py within each of your Django apps.

Then, within your Django project's urls.py you will use Django's include function to link it all together.

Viewing your component

To test your new Django view, run the following command to start up a development web server.

python manage.py runserver

Now you can navigate to your Django project URL that contains a ReactPy component, such as http://127.0.0.1:8000/example/ (from the previous step).

If you copy-pasted our example component, you will now see your component display "Hello World".

Do not use manage.py runserver for production

This command is only intended for development purposes. For production deployments make sure to read Django's documentation.

Learn more

Congratulations! If you followed the previous steps, you have now created a "Hello World" component using ReactPy-Django!

Deep Dive

The docs you are reading only covers our Django integration. To learn more, check out one of the following links:

Additionally, the vast majority of tutorials/guides you find for ReactJS can be applied to ReactPy.

Last update: December 2, 2024
Authors: Mark Bakhit