UI component library

[JuroOravec]

Intro

This thread is meant to be the main place for discussing building component library / design system on top of Django + django-components (DC).

When I refer to (UI) component library or a design system, I mean a package/library of pre-made UI components (like material design).

As an example, most of the time I'll refer to Vuetify, because:

1. I have the most experience with that, and I think it's made and documented very well
2. Using Django templates with django-components feels closer to using Vue templates than React, and Vuetify is based on Vue. So a component library for Django/DC might have similar constraints, and thus might end up with a similar interface.
3. AlpineJS and HTMX are two popular libraries for sparkling JS/interactivity onto HTML. In my project we're using AlpineJS, so I have much better awareness of how to do things with AlpineJS than with HTMX.
   Moreover, though, AlpineJS uses reactivity system from Vue (fundamentals, in depth). Since Vuetify is also based on Vue, this means that inspecting Vuetify's internal implementation of components can be a good approximation of how it could be implemented with AlpineJS.

Interface

Components would be used as django-components (DC) Components, so like from this example:

{% component "tabs" attrs:class="p-6 h-full" %}
  {% component "tab_item" header="Tab 1" %}
    <p>
      hello from tab 1
    </p>
    {% component "button" %}
      Click me!
    {% endcomponent %}
  {% endcomponent %}

  {% component "tab_item" header="Tab 2" %}
    Hello this is tab 2
  {% endcomponent %}
{% endcomponent %}

Since they would be DC Components, they could be used also in Python like so:

Tabs.render(
	kwargs={
		"attrs:class": "p-6 h-full",
	},
	slots={
		"content":  """
		 	{% component "tab_item" header="Tab 1" %}
			...
		"""
	}
)

They would be limited in the same way as django-components is. Meaning that the components would have to be used with Django templating language. And if django-components ever supports Jinja2, then the components could be used with Jinja2 too.

Implementation notes

AlpineJS vs HTMX vs plain JS vs other

As mentioned above, since I work with AlpineJS, I'm mainly focusing on that.

Moreover, though, UI components based on AlpineJS and HTMX would fundamentally have different behaviour and implementation. Based on how I've seen that the two have been used:

• AlpineJS is like a mini-Vue - it has the concept of components and isolation (to some extend), event passing, reactivity. AlpineJS makes sense for rich interactions - where a page is loaded, and user interactions trigger changes on the same page, captured and processed by the JS layer.

• HTMX I've seen mostly around the concept of HTML fragments - where when user interacts with the page, it triggers a request, which returns and updated section of HTML (fragment), and the new fragment is then inserted. I don't know if HTMX has any support for "components" or isolation.

Because if this, I think that if we were to make a component library for HTMX, it would not consider itself with reactivity. In other words, the library components would make it easier to make static HTML, that's it. Because if we then wanted to change the state of the UI, we'd make a request to generate the updated HTML, which would again generate static HTML.

On the other hand, since AlpineJS supports reactivity, this approach would be closer to server-side rendering with Vue/React - First the HTML is generated, but once it gets to user's browser, it "boots up" the JS state (hydration), and handles changes through JS, until user navigates to a new page.

In theory, you could have a singular interface defined as Django components, and through some settings you could switch whether, behind the scene, the components would use AlpineJS or HTMX or neither. But the AlpineJS mode would probably be more featureful, because it can handle reactivity. And that raises question on whether the two implementations should then have the same interface, if they don't have the same capabilities.

So that's why I'm drawn to implement the components in AlpineJS.

Passing data from Python (Django) to AlpineJS components

Since the interface would be in Python (Django template), but the component would eventually exist as AlpineJS component, we'd need a way to pass data from Python to JS.

This is possible because AlpineJS has an init hook, which can be used to set the initial state.

So what I do is that, when the Django template is being rendered, I set data-init (data attribute) to a JSON with initial state, e.g.:

<div
  x-data="tabs"
  data-init="{{ tabs_data|json|escape }}"
  {% html_attrs attrs %}
>
</div>

Where tabs_data looks like this:

"tabs_data": {"name": name},

So effectively the HTML looks like this:

<div
  x-data="tabs"
  data-init="{ \"name\": \"my_tab_name\" }"
>

Then, on the AlpineJS side, the data is read as JSON from the data-init attribute, and the component state is populated from it:

Alpine.data("tabs", () => ({
  // Variables
  name: null,

  // Methods
  init() {
    if (this.$el.dataset['init']) {
      const { name } = JSON.parse(this.$el.dataset['init']);
	  this.name = name;
	  ...
	}
  },
}));

So this is the same as the concept of hydration in other frameworks.

Passing data down within AlpineJS

For some more complex components, it may be necessary to "bind" data from parent component to child component. "Binding" meaning to pass it down, but keeping it reactive. So when the data in parent AlpineJS component changes, and that data is passed to the child, then the child AlpineJS component also receives the update.

ChatGPT suggested to use the $parent magic property from the alpine-parent package:

<div x-data="{ parentData: 'Hello from Parent' }">
    <div x-data>
        <p>Child Data: <span x-text="$parent.parentData"></span></p>
    </div>
</div>

However, in this example the data flow is inverted - the child AlpineJS component needs to know the data on the parent. Or to put it differently, the parent needs to implement child's interface for the child component to work.

So, instead, we may be better of if there was a way to do it other way around, so the child wouldn't have to access the parent component. One approach could be to define a custom directive, e.g. v-props, so we'd have a control over what data is passed from parent AlpineJS component to the child:

<div x-data="{ parentData: 'Hello from Parent' }">
    <div x-data x-props={ myText: parentData }>
        <p>Child Data: <span x-text="$props.myText"></span></p>
    </div>
</div>

Emitting events up within AlpineJS

Props are used to pass data down, events are used to send them up.

AlpineJS does support emitting ($dispatch) and listening (x-on) to events, so we'd just use that.

Running JS once vs per each component

AlpineJS already handles this for us. When we define an instance of AlpineJS component with x-data:

<div x-data="tabs">
	...
</div>

Then the component will be generated with its own state, and it will run init() method. So we don't have to take care of much else.

And when it comes to running one-off JS scripts, aka scripts that should run only once, no matter how many instances of that component is there, well for that we have the Media.js property on django-components Component class:

class MyComponent(Component):
	class Media:
		js = "runMeOnce.js"

To ensure that the runMeOnce.js really only executes once per page is out of scope for the component library, and is responsibility of django-components (see #478).

Configuring JS and CSS with variables passed into Django components

This is out of scope of component library, and should be handled in django-components.

Codebase

A component library like this should live in it's own project.

Non-goals

Web optimizations

Vuetify does more than just components - e.g. supports use of icon fonts, lazy-loading images, exposing CSS as SASS variables, etc.

With the component library, I want to focus on the functionality - that a component renders the HTML/CSS/JS and fulfills basic interactions. But features that feel like optimizations (lazy loading, etc) are out of scope.

Server interactions

If we compare django-components to e.g. django-unicorn or tetra then the latter two also manage the server-client communication to some extend. On the other hand, django-components is purely frontend, meaning concerned only with templating (generating HTML/JS/CSS), and leaves the server-client communication up to the user.

Hence, the components should respect this too. As an example, something like autocomplete component would require user to specify how to fetch data, so user has the freedom to whichever method they prefer.

Components

There is A LOT of components by Vuetify. To get a sense of what to focus on, I reviewed and ranked them:

High priority components

Name	Reason
Avatar	Simple and useful
Badge	Simple and useful
Breadcrumbs	Simple and useful
Btn	Very important, but loaded with features
Card	Very important, but loaded with features
Chip	Simple and useful
Divider	Simple and useful
Form	Very important and should be mostly logic
Icon	Very important, frequently used
Image	Very important, frequently used
List	Many subcomponent, but ultimately very useful
Menu	Very useful
ProgressCircular	Simple and useful
ProgressLinear	Simple and useful
Overlay	Used by dialogs and menus
SelectionControl	Required by input components, I think
SelectionControlGroup	Required by input components, I think
Sheet	Required by many other components
Tabs	Very useful, have it half-way figured out. But needs other underlying components.

Mid priority components

Name	Reason
Alert	Not top priority, but should be easy
BtnGroup	Less important as buttons themselves
BtnToggle	Less important as buttons themselves
Checkbox	Useful, as other inputs
ChipGroup	Useful, as other inputs
Code	Just styling, should be trivial
Counter	Used internally by other inputs?
Dialog	May be complex, but frequently used
ExpansionPanel	Useful, but handling many panels at the same time may be more difficult?
Field	Very useful, but very complex
FileInput	Useful, as other inputs
Hover	Niche but simple
Input	Useful, as other inputs
ItemGroup	Required by tabs and carousel
Kbd	Just styling, should be trivial
Label	Internal, but used by inputs?
Messages	Internal, but used by inputs?
OptInput	Useful, as other inputs
Radio	Useful, as other inputs
RadioGroup	Useful, as other inputs
Select	Useful, as other inputs
SlideGroup	Nice to have, but used by other tabs and others
Slider	Useful, as other inputs
Snackbar	Useful for operations, requires same underlying components as dialogs or menu
Switch	Useful, as other inputs
TextField	Useful, as other inputs
Textarea	Useful, as other inputs
Tooltip	Useful, should be trivial after Overlay is implemented
Validation	Not sure, but I think inputs will require this?

Mid-Low priority components

Name	Reason
Autocomplete	Useful as other inputs, but may be more complex
Combobox	Same reason as autocomplete
ConfirmEdit	User can build it themselves
DataIterator	Generic data table - very useful, but very complex
DataTable	Data table - very useful, but very complex
EmptyState	More niche, but not that hard to implement?
Footer	Simple, but low value
Pagination	Kinda useful, kinda simple
RangeSlider	Useful, maybe less oft used as other inputs?
Rating	Useful, maybe less oft used as other inputs?

Low priority components

Name	Reason
App	Keep in mind it provides the theme, but otherwise I would leave layout components for later
AppBar	I would leave layout components for later
Banner	While not too difficult, the sticky prop mght mean it would require layout components
Bottom navigation	I would leave layout components for later
Bottom sheet	Same reason as Bottom navigation
Carousel	Feels more niche
ColorPicker	Feels more niche, yet complex
DatePicker	Niche
DefaultsProvider	Mostly internal use?
Fab	Can be substituted by button or avatar?
Grids	Easily substituted with flex
InfiniteScroll	Nice to have
Layout	I would leave layout components for later
Lazy	Not sure if applicable
LocaleProvider	Less oft used?
Main	I would leave layout components for later
NavigationDrawer	I would leave layout components for later
NoSsr	Not sure if applicable?
OverflowBtn	Not sure what it does?
Parallax	Nice to have, only aesthetics
Responsive	internal component, not sure where used
SkeletonLoader	while useful, there's a lot of variants, so would be a lot of CSS fiddling
Sparkline	Feels fairly niche
Speeddial	Can be substituted with e.g. expansion panels
Stepper	Can be substituted with e.g. tabs?
SystemBar	I would leave layout components for later
Table	Unlike DataTable, this is just a wrapper for <table> HTML element?
ThemeProvider	Easy to implement, but nice to have
Timeline	Like Sparkline, kinda niche
Toolbar	I would leave layout components for later
Treeview	Like Sparkline, kinda niche
VirtualScroll	Nice to have
Transitions	Nice to have

[EmilStenstrom]

Very interesting summary! Looks viable to build a set of AlpineJS-components that's compatible with django-components.

To be clear: The total setup you are pushing for is Django + Django-components + AlpineJS? Would I be correct in saying that this would be mainly used for a SPA-like app? And not make use of django-components feature of rendering template fragments?

And the alternative would be Django + Django-components + HTMX, and then rendering things on the serverside and updating the components that way instead? Are there other options?

[JuroOravec]

Thanks!

Yup, you are right, what I have in mind is Django + Django-components + AlpineJS, and it would be SPA-like.

It could still make use of the template fragment rendering feature, but not to the extent as it would be used for HTMX. AlpineJS has a x-html directive, which one could theoretically use to swap parts of the HTML same way as HTMX does.

And yes, with Django + Django-components + HTMX, the conventional way would be to render and send the updated components from the server. Didn't work with HTMX, so can't tell how far one could push it, e.g. whether or not it would be possible to build more interactive components with HTMX.

And I guess other options depend on what's popular in the community - In theory, on one end of the spectrum, one could build an interactive component library but use vanilla JS instead of AlpineJS/HTMX, and just build it all up from scratch. On the other end of the spectrum, there could be something where the server holds the state and manages interactions, like with django-unicorn.

[JuroOravec]

Btw, huge update! This week, I was exploring this, and got the stack for Django + Django-component + AlpineJS + Vuetify working just today! As a proof of concept, I implemented Vuetify's VDivider component, as that's one of the simplest ones.

from typing import Any, Dict

from django_components import component, types


class AlpinuiDemo(component.Component):
    def get(self, request, *args, **kwargs):
        return self.render_to_response()

    def get_context_data(self, *args, **kwargs) -> Dict[str, Any]:
        return {}

    template: types.django_html = """
        {% component "Alpinui" %}
            {% component "ADivider" opacity=0.3 attrs:style="margin:20px" %}
                My content hello!
            {% endcomponent %}
        {% endcomponent %}
    """

Which then rendered something like this (straight line):

I gave the library a working title "Alpinui", and parked the code over at https://github.com/JuroOravec/alpinui/tree/main/packages/alpinui-django. I published the component library under django_alpinui.

Also made a video overview https://www.youtube.com/watch?v=V0tMYsy3RgQ.

What's great is that I didn't have to make any changes on the CSS, and I will need to update only about 5-10% of JS logic. Only the HTML needs to be rewritten from JSX to django template.

Basically what I did was to re-implement Vue's composition API in AlpineJS, which is possible because AlpineJS is using Vue's reactivity system. So in the best cases, I need to update only import statements.

Installation

1. Install dependencies

   pip install django_alpinui django_components

2. Add django_alpinui and django_components to INSTALLED_APPS in your settings.py

   INSTALLED_APPS = [
       "django_components",
       "django_components.safer_staticfiles",
       "django_alpinui",
       ...
   ]

3. Follow the installation instructions for django_components, so you can use its tags from within Django templates.

4. Add Alpinui JS and CSS dependencies

   <!DOCTYPE html>
   <html lang="en">
       <head>
           {% component "AlpinuiCss" %}{% endcomponent %}
           {% component "AlpinuiJs" %}{% endcomponent %}
       </head>
       <body>
       </body>
   </html>

NOTE: I'll close this one, as further discussion can continue on https://github.com/JuroOravec/alpinui

[EmilStenstrom]

Happy to hear you are making progress here! :)

[mikko-ahonen]

I have been adding some features to an existing Django application as components with Bootstrap + AlpineJS + HTMX + Django components. I have now 26 components, some of which are quite complex.

Only few of them are generic enough to be used from several places in my application. The main benefit of using components is that I can reload parts of the page when data has been updated, so the application has more modern feeling. Often the interrelationships between components is such that I cannot split them naturally into small components without passing so much state around that it becomes impractical.

I have two components that I need on almost all pages in the application:

• Typeahead, and especially selecting multiple referred objects as a list. Even this is only 80% generic, as the typeahead does not use JSON but HTML, meaning that the component rendering the results naturally calls the function to return the queryset.
• Modal. I have made a component on top of Bootstrap modal, which renders content -- often a form which is a regular Django view. Often it is used in places like editing or performing some other action on one entity on a list of entities, so you need to re-render the entity (or sometimes the list as well if you have changed something that impacts other entities, such as the key used to sort the entities) after the editing to show the changes.

[dbartenstein]

@JuroOravec wow! This looks amazing! 🙇

Can you please give us an update of the current state of the UI component library and where you’d be happy about help.

Btw, how does this compare to the component library created by Michael?
https://saashammer.com/lookbook/inspect/modal_component/small_modal/
https://testdriven.io/blog/django-reusable-components/

[dbartenstein]

@dbartenstein the only one I'm aware of that is published is: https://dhc.iwanalabs.com/ from @dylanjcastillo

@EmilStenstrom thanks for your reply. Are there any plans to create a default UI component library for django-components or will @JuroOravec’s alpinui become the de-facto standard once it’s done?

[tanssinet]

Hello! Sorry I have not responded earlier, I am in a middle of an extremely stressful situation in my personal life.

My "component library" is half-baked, at the moment it is ready only for my personal use on a few projects, not ready for open sourcing. It uses bootstrap 5, htmx and AlpineJS. I am not using AlpineJS components at the moment.

However, if you (or somebody else) wants to work on a component library, or just to see the code, I am willing to share it privately.

Most of the components are quite boring. For example I have a simple abstract (non-registered) delete component:

from django_components import component

class Delete(component.Component):
    template_name = "delete/delete.html"

    def get_context_data(self, obj, **kwargs):
        if not self.entity_class:
            raise ValueError("Instantiate only through subclasses, which must define entity_class")

        return {
            'view': self.view,
            'type_name': self.type_name,
            'obj': obj,
        }

    def delete(self, request, *args, **kwargs):
        obj_id = kwargs.get('pk', None)
        print(obj_id)
        obj = self.entity_class.objects.get(id=obj_id)

        obj.delete()

        context = self.get_context_data(obj=obj)

        return self.render_to_response(context, {})

and

{% load i18n %}
{% load component_tags %}
{% if obj %}
<button class="btn btn-outline-dark mx-1" hx-delete="{% url view obj.id %}" hx-confirm="{% trans 'Delete' %} {{ type_name }}?">
  <i class="bi bi-trash"></i>
</button>
{% endif %}

which is subclassed by a few concrete registered components, such as:

from django_components import component

from timeline.models import Event

from components.delete.delete import Delete

@component.register("event_delete")
class EventDelete(Delete):
    view = 'components:event-delete'
    entity_class = Event
    type_name = 'event'

Similarly, there exists inline_editor component.

The only more complex, generic, and/or interesting components are modal, typeahead and tags.

Modal is quite simple, just a wrapper for bootsrap modals.

Typeahead works well, but I am not happy about the code structure. It consists of two components, typeahead and typeahead_results. typeahead_results gets a parameter, which tells the query type, and this parameter is used within the typeahead to route to the correct hard-coded Django search. I think it should instead use similar abstract base class / concrete class structure as the delete.

Tags component is implemented using the typeahead component, and again, it has abstract base class and concrete implementation classes.

[dbartenstein]

Hello! Sorry I have not responded earlier, I am in a middle of an extremely stressful situation in my personal life.

My "component library" is half-baked, at the moment it is ready only for my personal use on a few projects, not ready for open sourcing. It uses bootstrap 5, htmx and AlpineJS. I am not using AlpineJS components at the moment.

@tanssinet sorry to hear that. Wish you all the best 🍀! And thanks for your offer! 🙇

Let me briefly explain to all participants of this discussion where we are heading. Several weeks ago we have successfully migrated our admin interface from Jazzmin to Unfold. Unfold uses tailwindcss and recently also introduced its own components. As we’re adding additional overviews, dashboard views and more interactivity for our admin users, we want to use a component library and therefore are looking for a UI component library so that we don’t have to start writing one from scratch. Currently we’re evaluating which path to pursue.

[JuroOravec]

@tanssinet Good luck, and if I can help you somehow, drop me a message on email.

[EmilStenstrom]

@tanssinet Same here, let me know if I can help.

@dbartenstein I did open a PR with unfold to consider basing unfold on this django-components instead of rolling their own. We'll see. The idea behind django-components is that there will be many libraries based on top of it, not just one. Which one works for you will depend on what CSS and JS framework you want to use.

[dbartenstein]

@JuroOravec

Regarding: #547 (reply in thread)

Can you please outline what alpinui will have more compared to just copying HTML from Tailwind examples and wrapping that in components? That would be very helpful to fully understand. Thanks! 🙇

[JuroOravec]

If you're not familiar, have a look at components at Vuetify, since Alpinui is a port of Vuetify, it will have the same features (or rather as were as of June / July this year).

Another big difference is that the Alpinui components are closer to how server-side rendered Vue / React behaves - you first pre-render the HTML on the server, setting the initial state, and then in the browser the components "hydrate". So you can use JS (AlpineJS) to manage the client-side state and interaction (e.g. changing the color or loading state of a button without having to make a server request).

On the other hand, when you copy HTML from Tailwind you have only the static HTML. So in that case I assume you'd use something like the "HTML over the wire" approach to replace bits of HTML using HTMX / AlpineJS / other to achieve interactivity.

You can use "HTML over the wire" even with Alpinui, but it's not the only option.

[dbartenstein]

@JuroOravec thanks! How easy is it to use TailwindCSS with Vuetify and in Alpinui? From what I read, Vuetify is Material, isn’t it?

[JuroOravec]

Yeah, Vuetify implements its own styling for Material design and lots of CSS utilities. Haven't tried using Tailwind with Vuetify myself yet, but based on some articles I found here and here:

• Currently, in Alpinui, the Vuetify CSS is generated from SASS as a single large CSS file. This large file contains all component CSS, CSS utilities, colors, etc...

  • That means that currently if you include a component like {% AButton %}, you still need to insert the Vuetify's CSS file as <link> for the button component to be styled.

  • Ideally instead of the monolithic CSS, Alpinui would load only the CSS used by the respective components, but that's a matter of optimization, and that's all still far away.

• So with this current setup, it looks like following should be possible:

  1. Alpinui could generate two such monolithic CSS files - one which would include the Vuetify CSS utilities and color classes, and other which would omit them (as outlined here).

  2. You as the user would choose which CSS file you want, and so you could opt out of using Vuetify' CSS utilities.

  • NOTE: The styling of the component does NOT depend on the CSS utilities being loaded in the browser.

  4. That means that you'd be able to load Tailwind CSS without conflicts next to Vuetify / Alpinui.

  5. And thus you should be able to do something like {% AButton class="font-bold" %}. That is, applying TailwindCSS to modify the styling of Vuetify components.