Basic Components - Server-side port of shadcn/ui using JinjaX, htmx, Alpine.js and Tailwind CSS

[phernandez]

Hi JinjaX community! 👋

I wanted to share Basic Components (https://components.basicmachines.co), a collection of reusable server-side components built with JinjaX, Tailwind CSS, and htmx based on shadcn/ui.

The project adapts shadcn/ui's component patterns for server-first Python web applications by integrating:

• JinjaX for server-side component composition
• htmx for dynamic DOM updates
• Alpine.js for lightweight client-side state management
• Tailwind CSS for utility-first styling

Here's a complete component example:

{#def
    className: str = "",
    variant: str = "default",
    size: str = "default",
    disabled: bool = False
#}
{% set baseClass = "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-white transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-zinc-950 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 dark:ring-offset-zinc-950 dark:focus-visible:ring-zinc-300" %}

{% set variantClass = {
    'default': 'bg-zinc-900 text-zinc-50 hover:bg-zinc-900/90 dark:bg-zinc-50 dark:text-zinc-900 dark:hover:bg-zinc-50/90',
    'destructive': 'bg-red-500 text-zinc-50 hover:bg-red-500/90 dark:bg-red-900 dark:text-zinc-50 dark:hover:bg-red-900/90',
    'outline': 'border border-zinc-200 bg-white hover:bg-zinc-100 hover:text-zinc-900 dark:text-zinc-50 dark:border-zinc-700 dark:bg-zinc-950 dark:hover:bg-zinc-800 dark:hover:text-zinc-50',
    'secondary': 'bg-zinc-100 text-zinc-900 hover:bg-zinc-100/80 dark:bg-zinc-800 dark:text-zinc-50 dark:hover:bg-zinc-800/80',
    'ghost': 'hover:bg-zinc-100 hover:text-zinc-900 dark:hover:bg-zinc-800 dark:hover:text-zinc-50',
    'link': 'text-zinc-900 underline-offset-4 hover:underline dark:text-zinc-50'
}[variant] %}

{% set sizeClass = {
    'default': 'h-10 px-4 py-2',
    'sm': 'h-9 rounded-md px-3',
    'lg': 'h-11 rounded-md px-8',
    'icon': 'h-10 w-10'
}[size] %}

<button
    class="{{ baseClass }} {{ variantClass }} {{ sizeClass }} {{ className }}"
    {% if disabled %}disabled{% endif %}
    {{ attrs.render() }}
>
    {{ content }}
</button>

And how you use it:

<Button
  variant="outline"
  class="mt-4"
  hx-get="/api/data"
  hx-target="#result"
  x-on:click="open = !open"
>
  Click me
</Button>

Key features:

• Typed component arguments
• Standardized component patterns
• Multiple variants with consistent styling
• Light/dark mode theming
• ARIA attributes and keyboard navigation
• Component composition for complex layouts

Installation & Development Tools:

• Components installed via CLI tool that handles dependencies:

  uvx --from basic-components components add dropdown_menu

• Components are copied directly into your project (no package dependency)
• Built-in analyzer to track component dependencies in the project metadata

  # Example analyzer output for dropdown_menu
  {
    "dropdown_menu": [
      "checkbox",
      "icons/ChevronRight",
      "radio"
    ]
  }

• Documented AI workflow for porting additional components:

The AI workflow has been particularly effective for maintaining consistency when porting components - I've used LLMs to handle the conversion of React/Tailwind patterns to JinjaX/htmx while preserving the styling and accessibility features.

The project is MIT licensed and welcomes contributions.

Documentation: https://components.basicmachines.co/ with working previews and usage code.
Source: https://github.com/basicmachines-co/basic-components

The project is in active development and I welcome feedback from the JinjaX community.

Thanks!

-Paul

[Hybridhash]

Really liked your work, i was also thinking of doing something similar currently i am relying on Flowbite with sprinkles of Alpine JS to maintain client side reactivity but liked your adoption of shadcn UI. Will try to adopt certain more components based on guidelines provided on website l.

[phernandez]

Thanks!