Jx

https://jx.scaletti.dev/
Admin
Jx is a Jinja-powered component framework for building reusable, composable UI components with...
Tokens:46,248
Snippets:517
Trust Score:6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Prefixed Catalog Folder Setup

Source: https://jx.scaletti.dev/docs/components

Example of setting up a catalog folder with a prefix for third-party component libraries.

```python
catalog.add_folder("vendor/ui-lib", prefix="ui")


```

--------------------------------

### Install Jx using uv

Source: https://jx.scaletti.dev/docs/quickstart

Use this command to install the Jx library with uv.

```bash
uv add jx
```

--------------------------------

### Example Class-Based Views

Source: https://jx.scaletti.dev/docs/working/django

Example views demonstrating the use of JxTemplateView and JxMixin for different page components. Ensure `Product` model is defined elsewhere.

```python
from django.views import View
from myproject.mixins import JxMixin, JxTemplateView


class HomeView(JxTemplateView):
    component_name = "pages/home.jinja"


class ProductListView(JxMixin, View):
    component_name = "pages/products.jinja"

    def get(self, request):
        products = Product.objects.all()
        return self.render_component({"products": products})

```

--------------------------------

### Complete FastAPI Example with Sessions and Templating

Source: https://jx.scaletti.dev/docs/working/fastapi

This comprehensive Python example sets up a FastAPI application with session management, static file serving, and a custom templating system using Jx. It includes routes for home, products, and product details, along with product creation using flash messages and redirects.

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request, Depends
from fastapi.responses import HTMLResponse, RedirectResponse
from fastapi.staticfiles import StaticFiles
from starlette.middleware.sessions import SessionMiddleware
from jx import Catalog
import os

# Configuration
is_production = os.getenv("ENV") == "production"
catalog = Catalog(auto_reload=not is_production)


# Flash messages
def flash(request: Request, message: str, category: str = "info"):
    if "_flashes" not in request.session:
        request.session["_flashes"] = []
    request.session["_flashes"].append({"message": message, "category": category})


def get_flashed_messages(request: Request):
    return request.session.pop("_flashes", [])


# Templates dependency
class Templates:
    def __init__(self, request: Request):
        self.request = request

    def render(self, component: str, status_code: int = 200, **context):
        html = catalog.render(
            component,
            globals={
                "request": self.request,
                "url_for": self.request.url_for,
                "static": lambda path: self.request.url_for("static", path=path),
                "messages": get_flashed_messages(self.request),
            },
            **context,
        )
        return HTMLResponse(html, status_code=status_code)

# App
app = FastAPI(lifespan=lifespan)
app.add_middleware(SessionMiddleware, secret_key="your-secret-key")
app.mount("/static", StaticFiles(directory="static"), name="static")


# Routes
@app.get("/", name="home")
def home(templates: Templates = Depends()):
    return templates.render("pages/home.jinja")


@app.get("/products", name="products")
def products(templates: Templates = Depends()):
    products = get_products()
    return templates.render("pages/products.jinja", products=products)


@app.get("/products/{product_id}", name="product_detail")
def product_detail(product_id: int, templates: Templates = Depends()):
    product = get_product(product_id)
    if not product:
        raise HTTPException(status_code=404)
    return templates.render("pages/product.jinja", product=product)


@app.post("/products", name="create_product")
def create_product(request: Request, templates: Templates = Depends()):
    # ... create product ...
    flash(request, "Product created!", "success")
    return RedirectResponse(url="/products", status_code=303)


```

--------------------------------

### Jx Catalog Setup for Multi-App Components

Source: https://jx.scaletti.dev/docs/working/django

Configures the Jx Catalog to load components from different folders, including app-specific ones with prefixes. Requires Jinja2 engine setup.

```python
from django.conf import settings
from django.template import engines
from jx import Catalog

_jinja2_env = engines["jinja2"].env

catalog = Catalog(
    jinja_env=_jinja2_env,
    auto_reload=settings.DEBUG,
)

# Shared components
catalog.add_folder(settings.BASE_DIR / "components")

# App-specific components with prefixes
catalog.add_folder(settings.BASE_DIR / "blog" / "components", prefix="blog")
catalog.add_folder(settings.BASE_DIR / "shop" / "components", prefix="shop")

```

--------------------------------

### Install Jx using pip

Source: https://jx.scaletti.dev/docs/quickstart

Use this command to install the Jx library with pip.

```bash
pip install jx
```

--------------------------------

### Basic FastAPI Setup with Jx

Source: https://jx.scaletti.dev/docs/working/fastapi

Initializes a FastAPI application and a Jx Catalog for rendering Jinja templates.

```python
from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from jx import Catalog

app = FastAPI()
catalog = Catalog("components/", auto_reload=True)


@app.get("/", response_class=HTMLResponse)
def home():
    return catalog.render("pages/home.jinja")
```

--------------------------------

### Asset Collection Example

Source: https://jx.scaletti.dev/docs/assets

Demonstration of recursive asset collection across imported components.

```jinja
{#import "./layout.jinja" as Layout #}
{#import "./card.jinja" as Card #}
{#css page.css #}

<Layout>
  <Card>...</Card>
</Layout>
```

```jinja
{#import "./header.jinja" as Header #}
{#css layout.css #}

<div>
  <Header />
  {{ content }}
</div>
```

```jinja
{#css header.css #}
<header>...</header>
```

```jinja
{#css card.css #}
<div class="card">{{ content }}</div>
```

```text
page.css
layout.css
header.css
card.css
```

--------------------------------

### Initialize Jx Catalog with Flask

Source: https://jx.scaletti.dev/docs/working/flask

Basic setup for integrating Jx with a Flask application.

```python
from flask import Flask
from jx import Catalog

app = Flask(__name__)
catalog = Catalog(
    "components/",
    auto_reload=app.debug,
)

@app.route("/")
def home():
    return catalog.render("pages/home.jinja")
```

--------------------------------

### View CLI output formats

Source: https://jx.scaletti.dev/docs/tools/check

Examples of default text output and structured JSON output for integration.

```bash
$ jx check myapp.setup:catalog
```

```text
✓ button.jinja - OK
✓ card.jinja - OK
✗ page.jinja:12 - Component 'Buton' used but not imported (did you mean 'Button'?)
✗ modal.jinja - Unknown import 'dialog.jinja' (did you mean 'dialogs/dialog.jinja'?)

4 components checked, 2 errors
```

```bash
$ jx check --format json myapp.setup:catalog
```

```json
{
  "checked": 4,
  "errors": [
    {
      "file": "page.jinja",
      "abs_path": "/path/to/components/page.jinja",
      "line": 12,
      "message": "Component 'Buton' used but not imported",
      "suggestion": "Button"
    },
    {
      "file": "modal.jinja",
      "abs_path": "/path/to/components/modal.jinja",
      "line": null,
      "message": "Unknown import 'dialog.jinja'",
      "suggestion": "dialogs/dialog.jinja"
    }
  ]
}
```

--------------------------------

### Add Blueprint-Specific Component Folders

Source: https://jx.scaletti.dev/docs/working/flask

Organize components by blueprint using prefixes. This example shows how to add shared components and blueprint-specific ones for 'blog' and 'admin'.

```python
from flask import Flask
from jx import Catalog

app = Flask(__name__)
catalog = Catalog(jinja_env=app.jinja_env, auto_reload=app.debug)

# Shared components
catalog.add_folder("components/")

# Blueprint-specific components
catalog.add_folder("blueprints/blog/components/", prefix="blog")
catalog.add_folder("blueprints/admin/components/", prefix="admin")

app.catalog = catalog

```

--------------------------------

### Dropdown Component Usage

Source: https://jx.scaletti.dev/docs/working/alpinejs

Example of how to use the `Dropdown` component, providing a label and content for the dropdown menu.

```html
<Dropdown label="Options">
  <a href="/profile">Profile</a>
  <a href="/settings">Settings</a>
  <hr>
  <a href="/logout">Logout</a>
</Dropdown>

```

--------------------------------

### add_package Method

Source: https://jx.scaletti.dev/docs/api/catalog

Registers components and optionally assets from an installed Python package.

```APIDOC
## POST /api/packages

### Description
Registers components and optionally assets from an installed Python package.

### Method
`add_package`

### Endpoint
`/api/packages`

### Parameters
#### Path Parameters
- **package_name** (str) - Required - The importable package name (e.g. "my_ui_kit").

#### Query Parameters
- **prefix** (str) - Required - Prefix for the components (e.g. "ui").

### Request Example
```python
catalog.add_package(package_name="my_ui_kit", prefix="ui")
```

### Response
#### Success Response (200)
- **None** - Indicates the package was successfully registered.
```

--------------------------------

### Usage of Conditional Layout Sections

Source: https://jx.scaletti.dev/docs/recipes/layouts

Examples demonstrating how to use the layout with conditional sections. The first example shows a full layout with a custom sidebar, while the second shows a minimal layout with both sidebar and footer disabled.

```jinja
{# Full layout with sidebar #}
<Layout title="Dashboard">
  {% fill sidebar %}
    <nav>Custom sidebar</nav>
  {% endfill %}
  <h1>Dashboard</h1>
</Layout>

{# Minimal layout without sidebar #}
<Layout title="Login" show_sidebar={{ false }} show_footer={{ false }}>
  <form>Login form</form>
</Layout>

```

--------------------------------

### Configure Assets in JinjaX

Source: https://jx.scaletti.dev/docs/from-jinjax

JinjaX requires middleware setup and specific catalog rendering to manage assets.

```python
# Requires middleware setup
app.wsgi_app = catalog.get_middleware(
    app.wsgi_app,
    autorefresh=app.debug,
)
```

```jinja
{#css mypage.css #}
{#js mypage.js #}

<Layout title="My Page">
  {{ catalog.render_assets() }}
  ...
</Layout>
```

--------------------------------

### Standard Jinja Template Example

Source: https://jx.scaletti.dev/

A traditional, tightly coupled Jinja template using standard blocks and includes.

```jinja
{% extends "layout.html" %}
{% block title %}My title{% endblock %}

{% block body %}
  {% for prod in products %}
  <div class="card product">
    <div class="card_header">
      <img src="{{ url_for(
        'static',
        prod.img_url or 'default.png'
      ) }}" />
      <h1>{{ prod.title }}</h1>
    </div>
    <div class="card_content">
      <div class="product_price">{{ prod.price }}</div>
      {{ prod.description }}
    </div>
  </div>
  {% endfor %}
  {% with items=products %}
    {% include "pagination.html" %}
  {% endwith %}
{% endblock %}
```

--------------------------------

### Example collected asset structure

Source: https://jx.scaletti.dev/docs/installable

The directory structure generated after running collect_assets.

```text
static/pkg/
  ui/
    button.css
    button.js
    card.css
```

--------------------------------

### Setup htmx in Layout

Source: https://jx.scaletti.dev/docs/working/htmx

Include the htmx script in the base layout template to enable functionality across the application.

```jinja
{#def title #}

<!DOCTYPE html>
<html>
<head>
  <title>{{ title }}</title>
  <script src="https://unpkg.com/htmx.org@2.0.4"></script>
  {{ assets.render_css() }}
</head>
<body>
  {{ content }}
  {{ assets.render_js() }}
</body>
</html>
```

--------------------------------

### Complete Flask Application with Jx Catalog

Source: https://jx.scaletti.dev/docs/working/flask

A full Flask application example demonstrating Jx Catalog integration for component rendering, routing, authentication, and error handling.

```python
from flask import Flask, redirect, url_for, flash, session, g, request
from flask_wtf.csrf import CSRFProtect
from jx import Catalog

app = Flask(__name__)
app.secret_key = "your-secret-key"
csrf = CSRFProtect(app)

# Create catalog with Flask's Jinja environment
catalog = Catalog(
    "components/",
    jinja_env=app.jinja_env,
    auto_reload=app.debug,
)

@app.before_request
def load_user():
    user_id = session.get("user_id")
    g.user = get_user_by_id(user_id) if user_id else None

@app.route("/")
def home():
    return catalog.render("pages/home.jinja")

@app.route("/login", methods=["GET", "POST"])
def login():
    if request.method == "POST":
        user = authenticate(request.form["email"], request.form["password"])
        if user:
            session["user_id"] = user.id
            flash("Welcome back!", "success")
            return redirect(url_for("dashboard"))
        flash("Invalid credentials", "error")
    return catalog.render("pages/login.jinja")

@app.route("/dashboard")
def dashboard():
    if not g.user:
        return redirect(url_for("login"))
    return catalog.render("pages/dashboard.jinja", user=g.user)

@app.errorhandler(404)
def not_found(e):
    return catalog.render("errors/404.jinja"), 404

if __name__ == "__main__":
    app.run(debug=True)


```

--------------------------------

### Relative Asset URLs

Source: https://jx.scaletti.dev/docs/assets

Example of declaring relative paths for assets.

```jinja
{#css card.css #}
{#js card.js #}
```

```html
<link rel="stylesheet" href="card.css">
<script type="module" src="card.js"></script>
```

--------------------------------

### Jinja2 Template for Static File Links

Source: https://jx.scaletti.dev/docs/working/fastapi

Example Jinja2 template demonstrating how to link to static assets like CSS and JavaScript using the `static` helper function.

```jinja
{#def title #}

<!DOCTYPE html>
<html>
<head>
  <title>{{ title }}</title>
  <link rel="icon" href="{{ static('favicon.ico') }}">
  {% for css in assets.collect_css() %}
    <link rel="stylesheet" href="{{ static(css) }}">
  {% endfor %}
</head>
<body>
  {{ content }}
  {% for js in assets.collect_js() %}
    <script type="module" src="{{ static(js) }}"></script>
  {% endfor %}
</body>
</html>

```

--------------------------------

### Tabs Component Usage

Source: https://jx.scaletti.dev/docs/working/alpinejs

An example demonstrating how to assemble the `Tabs`, `Tab`, and `TabPanel` components to create a functional tabbed interface.

```html
<Tabs default="overview">
  <div class="tab-list">
    <Tab name="overview">Overview</Tab>
    <Tab name="features">Features</Tab>
    <Tab name="pricing">Pricing</Tab>
  </div>

  <TabPanel name="overview">
    <h2>Overview</h2>
    <p>Overview content here.</p>
  </TabPanel>

  <TabPanel name="features">
    <h2>Features</h2>
    <p>Features content here.</p>
  </TabPanel>

  <TabPanel name="pricing">
    <h2>Pricing</h2>
    <p>Pricing content here.</p>
  </TabPanel>
</Tabs>

```

--------------------------------

### Usage of Nested App Layout

Source: https://jx.scaletti.dev/docs/recipes/layouts

Example of how to use the 'app.jinja' layout. It imports the layout and passes a title, rendering the main content within the app structure.

```jinja
{#import "layouts/app.jinja" as App #}

<App title="Dashboard">
  <h1>Dashboard</h1>
</App>

```

--------------------------------

### Jinja2 Template Usage with Prefixed Components

Source: https://jx.scaletti.dev/docs/working/django

Example Jinja2 template demonstrating how to import and use components from different apps using their prefixes. Assumes `Layout`, `PostCard`, and `ProductCard` components are available.

```jinja
{#import "layout.jinja" as Layout #}
{#import "@blog/post-card.jinja" as PostCard #}
{#import "@shop/product-card.jinja" as ProductCard #}

<Layout title="Home">
  <section>
    <h2>Latest Posts</h2>
    {% for post in posts %}
      <PostCard post={{ post }} />
    {% endfor %}
  </section>

  <section>
    <h2>Featured Products</h2>
    {% for product in products %}
      <ProductCard product={{ product }} />
    {% endfor %}
  </section>
</Layout>

```

--------------------------------

### Home Page using Basic Layout

Source: https://jx.scaletti.dev/docs/recipes/layouts

An example of a home page Jinja template that imports and uses the basic layout component, providing a title and content.

```jinja
{#import "../layout.jinja" as Layout #}

<Layout title="Home">
  <h1>Welcome!</h1>
  <p>This is the home page.</p>
</Layout>

```

--------------------------------

### Example of Component Instantiation with Attributes

Source: https://jx.scaletti.dev/docs/attrs

This shows a component being used with several attributes. 'text' is a defined argument, while 'id', 'disabled', and 'data-action' are extra attributes that will be collected by the attrs object.

```html
<Button text="Save" id="save-btn" disabled data-action="save" />

```

--------------------------------

### Usage of Blueprint-Specific Components in Templates

Source: https://jx.scaletti.dev/docs/working/flask

Import and use blueprint-specific components within your templates. This example shows how to import and render 'post-card' components in blog templates.

```jinja
{#import "@blog/post-card.jinja" as PostCard #}

{% for post in posts %}
  <PostCard post={{ post }} />
{% endfor %}


```

--------------------------------

### Add Package to Catalog

Source: https://jx.scaletti.dev/docs/api/catalog

Registers components and assets from an installed Python package with an optional prefix.

```python
add_package(
    package_name: str,
    *,
    prefix: str
) -> None
```

--------------------------------

### Create a Blueprint-Specific Jinja Component

Source: https://jx.scaletti.dev/docs/working/flask

Define a Jinja component for a specific blueprint. This example creates a 'post-card' component for the 'blog' blueprint.

```jinja
{#import "card.jinja" as Card #}
{#def post #}

<Card class="post-card">
  <h2><a href="{{ url_for('blog.post', slug=post.slug) }}">{{ post.title }}</a></h2>
  <p>{{ post.excerpt }}</p>
</Card>


```

--------------------------------

### Modal Component Usage

Source: https://jx.scaletti.dev/docs/working/alpinejs

Example of using the `Modal` component, defining trigger, title, content, and footer slots. Also shows how to trigger the modal from another element.

```html
<Modal name="confirm" title="Confirm Action">
  {% fill trigger %}
    <button class="btn btn-danger">Delete Item</button>
  {% endfill %}

  <p>Are you sure you want to delete this item?</p>

  {% fill footer %}
    <div class="modal-footer">
      <button @click="open = false">Cancel</button>
      <button class="btn btn-danger">Delete</button>
    </div>
  {% endfill %}
</Modal>

{# Or trigger from elsewhere #}
<button @click="$dispatch('open-modal-confirm')">Delete</button>

```

--------------------------------

### Define a Jinja Component

Source: https://jx.scaletti.dev/docs/quickstart

Create a Jinja template for a reusable component. This example defines a 'card' component that accepts 'title', 'content', and 'url' as parameters.

```jinja
{#def title, url #}

<div class="bg-white shadow rounded border p-4">
  <h2 class="m-0 text-gray-800">{{ title }}</h2>
  <p>{{ content }}</p>
  <a href="{{ url }}" class="text-teal-600">Read more</a>
</div>
```

--------------------------------

### Button Component Usage

Source: https://jx.scaletti.dev/docs/attrs

Example of how to use the Button component, passing custom attributes like `text`, `variant`, `id`, and `disabled`.

```html
<Button text="Save" variant="success" id="save-btn" disabled />

```

--------------------------------

### Best Practice: Document Expected Attributes

Source: https://jx.scaletti.dev/docs/attrs

Shows how to document expected attributes for a component using a comment, guiding users on common attributes like `class`, `id`, `disabled`, and `data-*`.

```jinja
{#def text #}
{# Common attrs: class, id, disabled, data-* #}

<button {{ attrs.render(class="btn") }}>
  {{ text }}
</button>

```

--------------------------------

### Catalog Initialization with Folder

Source: https://jx.scaletti.dev/docs/catalog

Demonstrates equivalent ways to initialize a Catalog with a component folder.

```python
# These are equivalent:
catalog = Catalog("components/")

catalog = Catalog()
catalog.add_folder("components/")
```

--------------------------------

### Usage of Nested Auth Layout

Source: https://jx.scaletti.dev/docs/recipes/layouts

Example of how to use the 'auth.jinja' layout. It imports the layout and passes a title, rendering the form content within the authentication card structure.

```jinja
{#import "layouts/auth.jinja" as Auth #}

<Auth title="Login">
  <h1>Sign In</h1>
  <form>...</form>
</Auth>

```

--------------------------------

### Use Jx Catalog in Django Views

Source: https://jx.scaletti.dev/docs/working/django

Render Jx templates using the catalog in Django views. This example shows rendering a home page and a product list page, passing data as needed.

```python
from django.http import HttpResponse
from myproject.components import catalog


def home(request):
    return HttpResponse(catalog.render("pages/home.jinja"))

def product_list(request):
    products = Product.objects.all()
    return HttpResponse(
        catalog.render("pages/products.jinja", products=products)
    )

```

--------------------------------

### Component Usage with Extra Attributes

Source: https://jx.scaletti.dev/docs/attrs

An example of how to instantiate a component, passing declared arguments and additional attributes that will be handled by the attrs object. Here, 'title' is a declared argument, while 'class', 'id', and 'data-index' are collected as attrs.

```html
<Card title="Hello" class="card-primary" id="main-card" data-index="1" />

```

--------------------------------

### About Page using Navigation Highlighting Layout

Source: https://jx.scaletti.dev/docs/recipes/layouts

An example of an 'about' page that uses the layout with navigation highlighting. It passes 'about' as the 'current_page' to ensure the 'About' link is marked as active.

```jinja
{#import "layout.jinja" as Layout #}

<Layout title="About Us" current_page="about">
  <h1>About Us</h1>
</Layout>

```

--------------------------------

### Get All Attributes as Dictionary

Source: https://jx.scaletti.dev/docs/api/attrs

Access the 'as_dict' property to get an ordered dictionary of all attributes and properties, sorted by name.

```python
attrs = Attrs({
"class": "lorem ipsum",
"data_test": True,
"hidden": True,
"aria_label": "hello",
"id": "world",
})
attrs.as_dict
```

```python
{
    "aria_label": "hello",
    "class": "lorem ipsum",
    "id": "world",
    "data_test": True,
    "hidden": True
}
```

--------------------------------

### Custom Render Loop for Static Files

Source: https://jx.scaletti.dev/docs/working/flask

Implement a custom render loop to generate links for static CSS files using `url_for`. This example is within a layout Jinja component.

```jinja
<head>
  {% for css_file in assets.collect_css() %}
    <link rel="stylesheet" href="{{ url_for('static', filename=css_file) }}">
  {% endfor %}
</head>


```

--------------------------------

### Define package entry points

Source: https://jx.scaletti.dev/docs/installable

Expose component and asset paths in the package's __init__.py file.

```python
from pathlib import Path

JX_COMPONENTS = Path(__file__).parent / "components"
JX_ASSETS = Path(__file__).parent / "assets"
```

--------------------------------

### Initialize JX Component Catalog

Source: https://jx.scaletti.dev/docs/working/django

Sets up the JX Catalog using the configured Jinja2 engine and registers a components folder.

```python
from django.conf import settings
from django.template import engines
from jx import Catalog

_jinja2_env = engines["jinja2"].env

catalog = Catalog(
    jinja_env=_jinja2_env,
    auto_reload=settings.DEBUG,
)
catalog.add_folder(settings.BASE_DIR / "components")
```

--------------------------------

### Get component data

Source: https://jx.scaletti.dev/docs/api/catalog

Retrieves component data from the cache, re-processing if the file has been updated.

```python
get_component_data(
    relpath: str
) -> jx.catalog.CData
```

--------------------------------

### Create a Jx Catalog

Source: https://jx.scaletti.dev/docs/quickstart

Initialize a Jx Catalog instance pointing to the directory where your components will be stored.

```python
from jx import Catalog

catalog = Catalog("components/")
```

--------------------------------

### Catalog Constructor

Source: https://jx.scaletti.dev/docs/api/catalog

Initializes a new Catalog instance. It can scan a folder for components and accept various configurations for Jinja rendering and asset resolution.

```APIDOC
## Catalog Constructor

### Description
Initializes a new Catalog instance. It can scan a folder for components and accept various configurations for Jinja rendering and asset resolution.

### Method
`Catalog`

### Parameters
#### Path Parameters
- **folder** (str | pathlib._local.Path | None) - Optional - Folder path to scan for components.

#### Keyword Parameters
- **jinja_env** (jinja2.environment.Environment | None) - Optional Jinja2 environment to use for rendering.
- **extensions** (list | None) - Optional extra Jinja2 extensions to add to the environment.
- **filters** (dict[str, typing.Any] | None) - Optional extra Jinja2 filters to add to the environment.
- **tests** (dict[str, typing.Any] | None) - Optional extra Jinja2 tests to add to the environment.
- **auto_reload** (bool) - Default: `True`. Whether to check the last-modified time of component files and automatically re-process them if they change.
- **asset_resolver** (collections.abc.Callable[[str, str], str] | None) - Optional callable that transforms asset URLs for components.
- **globals** (Any) - Variables to make available to all components by default.

### Request Example
```python
from pathlib import Path

catalog = Catalog(folder=Path("/path/to/components"), auto_reload=False)
```

### Response
#### Success Response (200)
- **None** - Initializes the Catalog object.
```

--------------------------------

### Catalog Constructor Options

Source: https://jx.scaletti.dev/docs/catalog

Configure Catalog with various options including folder, Jinja environment, extensions, filters, tests, auto-reload, and asset resolver.

```python
catalog = Catalog(
    folder="components/",       # Optional initial folder
    jinja_env=None,             # Custom Jinja2 environment
    extensions=None,            # Extra Jinja2 extensions
    filters=None,               # Custom template filters
    tests=None,                 # Custom template tests
    auto_reload=True,           # Auto-detect file changes
    asset_resolver=None,        # Asset URL resolver callback
    **globals                   # Global template variables
)
```

--------------------------------

### Django Migration

Source: https://jx.scaletti.dev/docs/from-jinjax

Update Django integration by removing the JinjaX extension and simplifying catalog setup.

```python
# Before
import jinjax

env.add_extension(jinjax.JinjaX)
catalog = jinjax.Catalog(jinja_env=env)
catalog.add_folder("components")

# After
import jx

catalog = jx.Catalog("components", jinja_env=env)
```

--------------------------------

### Get component signature

Source: https://jx.scaletti.dev/docs/api/catalog

Returns metadata about a component, including arguments, slots, and associated CSS/JS files.

```python
get_signature(
    relpath: str
) -> dict[str, typing.Any]
```

--------------------------------

### Access Flask Globals in Components

Source: https://jx.scaletti.dev/docs/working/flask

Example of using Flask template utilities within a Jx component.

```jinja
<nav>
  <a href="{{ url_for('home') }}">Home</a>
  <a href="{{ url_for('about') }}">About</a>
  {% if session.get('user_id') %}
    <a href="{{ url_for('profile') }}">Profile</a>
    <a href="{{ url_for('logout') }}">Logout</a>
  {% else %}
    <a href="{{ url_for('login') }}">Login</a>
  {% endif %}
</nav>
```

--------------------------------

### Importing Components from Prefixed Catalog Folders

Source: https://jx.scaletti.dev/docs/components

Shows how to import components when their catalog folder has been assigned a prefix.

```jinja
{#import "@ui/button.jinja" as Button #}
{#import "@ui/modal.jinja" as Modal #}


```

--------------------------------

### Initialize Jx Catalog

Source: https://jx.scaletti.dev/docs/from-jinjax

Initialize the Jx catalog using the new positional folder argument and keyword arguments for globals.

```python
catalog = jx.Catalog(
    "components/",        # optional folder shortcut (new)
    site_name="My Site",  # globals are now **kwargs, not a dict
)
```

--------------------------------

### Good Practice: Default Classes

Source: https://jx.scaletti.dev/docs/attrs

Illustrates the best practice of providing default classes to components using `attrs.render(class='btn')` to ensure base styling is always applied.

```jinja
{# ✅ Good - ensures base styling #}
<button {{ attrs.render(class="btn") }}>

{# ❌ Bad - user must always provide class #}
<button {{ attrs.render() }}>

```

--------------------------------

### Instantiate a component

Source: https://jx.scaletti.dev/docs/api/catalog

Returns a component object based on its relative path.

```python
get_component(
    relpath: str
) -> jx.component.Component
```

--------------------------------

### Import a Component with an Alias

Source: https://jx.scaletti.dev/docs/components

Demonstrates the basic syntax for importing a component and assigning it an alias. The alias must be PascalCase.

```jinja
{#import "path/to/component.jinja" as Name #}


```

--------------------------------

### Card Component Usage

Source: https://jx.scaletti.dev/docs/attrs

Example of using the Card component with a title and custom attributes like `class` and `data-card-id`.

```html
<Card title="Welcome" class="shadow-lg" data-card-id="123">
  <p>Card content here</p>
</Card>

```

--------------------------------

### Organizing Assets

Source: https://jx.scaletti.dev/docs/assets

Recommended directory structure and absolute path declaration for component assets.

```text
components/
  card/
    card.jinja
    card.css
    card.js
  button/
    button.jinja
    button.css
    button.js
```

```jinja
{#css /static/components/card/card.css #}
{#js /static/components/card/card.js #}
```

--------------------------------

### Jx CLI Validation Command

Source: https://jx.scaletti.dev/docs/components

Command-line interface command to validate all components within a specified application setup.

```bash
❯❯ jx check myapp.setup:catalog


```

--------------------------------

### Run asset collection via CLI

Source: https://jx.scaletti.dev/docs/installable

Execute asset collection as a build or deployment step.

```bash
jx collect_assets myapp.setup:catalog ./static/pkg
```

--------------------------------

### Get All Classes as a String

Source: https://jx.scaletti.dev/docs/api/attrs

The 'classes' property returns all HTML classes separated by a space. Use 'set' to modify classes.

```python
attrs = Attrs({"class": "italic bold bg-blue wide abcde"})
attrs.set(class="bold text-white")
print(attrs.classes)
```

```python
italic bold bg-blue wide abcde text-white
```

--------------------------------

### Render components from files

Source: https://jx.scaletti.dev/docs/catalog

Use render to display components by path. Pass data via keyword arguments or globals for shared access.

```python
html = catalog.render("page.jinja", title="Hello", user=current_user)
```

```python
# Pass data as keyword arguments
html = catalog.render(
    "user-profile.jinja",
    user=user,
    posts=posts,
    show_email=True,
)

# Or use globals for values needed by child components too
html = catalog.render(
    "page.jinja",
    globals={"request": request, "csrf_token": token},
    title="Dashboard",
)
```

--------------------------------

### Use Card Component with Content

Source: https://jx.scaletti.dev/docs/components

Demonstrates how to use the 'Card' component, passing a title and HTML content.

```html
<Card title="Hello">
  <p>This becomes the content!</p>
</Card>


```

--------------------------------

### Retrieve Attribute Value with Default

Source: https://jx.scaletti.dev/docs/api/attrs

The 'get' function retrieves an attribute's value, returning a specified default if the attribute does not exist.

```python
attrs = Attrs({"lorem": "ipsum", "hidden": True})

attrs.get("lorem", default="bar")
'ipsum'

attrs.get("foo")
None

attrs.get("foo", default="bar")
'bar'

attrs.get("hidden")
True
```

--------------------------------

### Use Relative Imports for Portability

Source: https://jx.scaletti.dev/docs/from-jinjax

Demonstrates using relative paths for component imports to simplify project reorganization.

```jinja
{#import "layouts/app.jinja" as App #}
{#import "./profile-card.jinja" as ProfileCard #}
{#import "./avatar.jinja" as Avatar #}
{#import "components/feed/post-list.jinja" as PostList #}
{#import "components/feed/post-card.jinja" as PostCard #}
{#def user, posts #}

<App title="User Profile">
  <ProfileCard user={{ user }}>
    <Avatar user={{ user }} size="large" />
  </ProfileCard>

  <PostList>
    {% for post in posts %}
      <PostCard post={{ post }} />
    {% endfor %}
  </PostList>
</App>
```

--------------------------------

### Wrapped Button Component Usage

Source: https://jx.scaletti.dev/docs/attrs

Example of using a component that forwards attributes, showing how `class` and `disabled` are passed down to the underlying Button component.

```html
<WrappedButton text="Save" class="primary" disabled />

```

--------------------------------

### Python Package Without Assets

Source: https://jx.scaletti.dev/docs/installable

Example of a Python package that only provides components and omits JX_ASSETS. The asset_resolver will not be called for this package's components.

```python
from pathlib import Path

JX_COMPONENTS = Path(__file__).parent / "icons"

```

--------------------------------

### Component Using Global Context Variables

Source: https://jx.scaletti.dev/docs/working/flask

A Jinja component that utilizes globally injected variables like 'current_year' and 'site_name'. This example is for a footer component.

```jinja
<footer>
  <p>&copy; {{ current_year }} {{ site_name }}</p>
</footer>


```

--------------------------------

### Input Component Usage

Source: https://jx.scaletti.dev/docs/attrs

Example of using the Input component with various attributes for email input, including `name`, `label`, `type`, `required`, `placeholder`, and `autocomplete`.

```html
<Input
  name="email"
  label="Email Address"
  type="email"
  required
  placeholder="you@example.com"
  autocomplete="email"
/>

```

--------------------------------

### Run Migration Script

Source: https://jx.scaletti.dev/docs/from-jinjax

Command to execute the automated migration tool.

```bash
uvx https://raw.githubusercontent.com/jpsca/jx-migrate/main/migrate.py
```

--------------------------------

### List all components

Source: https://jx.scaletti.dev/docs/api/catalog

Returns a list of all registered component relative paths.

```python
list_components() -> list[str]
```

--------------------------------

### Absolute Component Imports

Source: https://jx.scaletti.dev/docs/components

Shows how to import components using paths relative to a catalog folder, useful for shared components.

```jinja
{#import "components/button.jinja" as Button #}
{#import "layouts/base.jinja" as Base #}


```

--------------------------------

### Adding Multiple Component Folders

Source: https://jx.scaletti.dev/docs/catalog

Register multiple folders containing components with the Catalog.

```python
catalog = Catalog()
catalog.add_folder("components/")
catalog.add_folder("layouts/")
```

--------------------------------

### Component File Naming and Alias Convention

Source: https://jx.scaletti.dev/docs/components

Illustrates how component file names can use various conventions, but the import alias must be PascalCase to differentiate from HTML tags.

```jinja
{#import "user-card.jinja" as UserCard #}
{#import "form_input.jinja" as FormInput #}

<UserCard />   {# Component #}
<div />        {# HTML #}


```

--------------------------------

### Handling Multiple Folders with Same Prefix

Source: https://jx.scaletti.dev/docs/catalog

Illustrates how the Catalog resolves components when multiple folders share the same prefix; the first added folder takes precedence.

```python
catalog.add_folder("my-components/")      # Has button.jinja
catalog.add_folder("fallback-components/") # Also has button.jinja

# "button.jinja" resolves to my-components/button.jinja
```

--------------------------------

### Page using Layout with Slots

Source: https://jx.scaletti.dev/docs/recipes/layouts

An example of a page template that utilizes the slot-based layout. It fills the 'head', 'header', and 'scripts' slots with custom content, overriding defaults.

```jinja
{#import "layout.jinja" as Layout #}

<Layout title="Dashboard">
  {% fill head %}
    <meta name="robots" content="noindex">
  {% endfill %}

  {% fill header %}
    <nav>
      <a href="/dashboard">Dashboard</a>
      <a href="/settings">Settings</a>
    </nav>
  {% endfill %}

  <h1>Dashboard</h1>
  <p>Welcome back!</p>

  {% fill scripts %}
    <script>console.log('Page loaded');</script>
  {% endfill %}
</Layout>

```

--------------------------------

### Compare JinjaX and Jx Component Syntax

Source: https://jx.scaletti.dev/docs/from-jinjax

Comparison between the verbose JinjaX namespaced approach and the cleaner Jx explicit import style.

```jinja
{#def user, posts #}
<Layouts.App title="User Profile">
  <Components.User.ProfileCard user={{ user }}>
    <Components.User.Avatar user={{ user }} size="large" />
  </Components.User.ProfileCard>

  <Components.Feed.PostList>
    {% for post in posts %}
      <Components.Feed.PostCard post={{ post }} />
    {% endfor %}
  </Components.Feed.PostList>
</Layouts.App>
```

```jinja
{#import "layouts/app.jinja" as App #}
{#import "components/user/profile-card.jinja" as ProfileCard #}
{#import "components/user/avatar.jinja" as Avatar #}
{#import "components/feed/post-list.jinja" as PostList #}
{#import "components/feed/post-card.jinja" as PostCard #}
{#def user, posts #}

<App title="User Profile">
  <ProfileCard user={{ user }}>
    <Avatar user={{ user }} size="large" />
  </ProfileCard>

  <PostList>
    {% for post in posts %}
      <PostCard post={{ post }} />
    {% endfor %}
  </PostList>
</App>
```

--------------------------------

### Preserving Specific Attributes in Jinja

Source: https://jx.scaletti.dev/docs/attrs

Example of how to extract specific attributes like `id` using `attrs.get()` before rendering the rest of the attributes with `attrs.render()`. This allows for controlled attribute application.

```jinja
{#def title #}

{# Get specific attrs before rendering #}
{% set custom_id = attrs.get("id", "default-id") %}

<div id="{{ custom_id }}" class="card">
  <h3>{{ title }}</h3>
  <div {{ attrs.render() }}>{# Other attrs go here #}
    {{ content }}
  </div>
</div>

```

--------------------------------

### Catalog Class Constructor

Source: https://jx.scaletti.dev/docs/api/catalog

Initializes the Catalog manager. Configure Jinja2 environment, extensions, filters, tests, and global variables.

```python
Catalog(
    folder: str | pathlib._local.Path | None = None,
    *, 
    jinja_env: jinja2.environment.Environment | None = None,
    extensions: list | None = None,
    filters: dict[str, typing.Any] | None = None,
    tests: dict[str, typing.Any] | None = None,
    auto_reload: bool = True,
    asset_resolver: collections.abc.Callable[[str, str], str] | None = None,
    **globals: Any
) -> None
```

--------------------------------

### Component Asset Declaration with Absolute Paths

Source: https://jx.scaletti.dev/docs/working/flask

Declare component assets using absolute paths that map to your static folder. This example uses a CSS file for a card component.

```jinja
{#css /static/css/card.css #}
{#def title #}

<div {{ attrs.render(class="card") }}>
  <h3>{{ title }}</h3>
  {{ content }}
</div>


```

--------------------------------

### Adding Folders with Prefixes

Source: https://jx.scaletti.dev/docs/catalog

Namespace components from different directories using prefixes for organization.

```python
catalog.add_folder("components/")
catalog.add_folder("vendor/ui-kit/", prefix="ui")
catalog.add_folder("vendor/icons/", prefix="icons")
```

```jinja
{#import "button.jinja" as Button #}
{#import "@ui/modal.jinja" as Modal #}
{#import "@icons/check.jinja" as CheckIcon #}
```

--------------------------------

### Get All Attributes as Dictionary with attrs.as_dict

Source: https://jx.scaletti.dev/docs/attrs

Retrieve all attributes collected by the attrs object as a Python dictionary using the attrs.as_dict property. This allows for iteration and programmatic access to all attribute key-value pairs.

```html
{% set all_attrs = attrs.as_dict %}

{% for key, value in all_attrs.items() %}
  <p>{{ key }}: {{ value }}</p>
{% endfor %}

```

--------------------------------

### Integrate with web frameworks

Source: https://jx.scaletti.dev/docs/catalog

Configure Jx Catalog for use within Flask or FastAPI applications.

```python
from flask import Flask, url_for
from jx import Catalog

app = Flask(__name__)
catalog = Catalog(
    "components/",
    auto_reload=app.debug,
    url_for=url_for,  # Make url_for available in components
)

@app.route("/")
def home():
    return catalog.render("pages/home.jinja", products=get_products())
```

```python
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from jx import Catalog

app = FastAPI()
catalog = Catalog("components/", auto_reload=True)

@app.get("/", response_class=HTMLResponse)
def home(request: Request):
    return catalog.render(
        "pages/home.jinja",
        globals={"request": request},
        products=get_products(),
    )
```

--------------------------------

### Integrate with Build Tools

Source: https://jx.scaletti.dev/docs/assets

Reference bundled assets generated by tools like Vite or Webpack.

```jinja
{#css /dist/card.css #}
{#js /dist/card.js #}
```

```html
<link rel="stylesheet" href="/dist/card.abc123.css">
<script type="module" src="/dist/card.def456.js"></script>
```

--------------------------------

### Merge Classes with Attrs

Source: https://jx.scaletti.dev/docs/attrs

The 'class' attribute is handled specially by attrs.render() to merge classes instead of replacing them. This example demonstrates merging a default class with a class passed during component instantiation.

```html
{#def text #}

<button {{ attrs.render(class="btn") }}>
  {{ text }}
</button>

```

```html
<Button text="Save" class="btn-primary" />

```

```html
<button class="btn btn-primary">Save</button>

```

--------------------------------

### Render Component with Attrs and Default Attributes

Source: https://jx.scaletti.dev/docs/attrs

Provide default attributes to attrs.render() which will be merged with or overridden by attributes passed to the component. This example sets default class and type attributes for a button.

```html
<button {{ attrs.render(class="btn", type="button") }}>
  {{ content }}
</button>

```

--------------------------------

### Integrating with Existing Jinja2 Environment

Source: https://jx.scaletti.dev/docs/catalog

Use a pre-existing Jinja2 environment with the Catalog, useful for framework integration.

```python
from jinja2 import Environment

env = Environment()
env.globals["my_func"] = my_function
env.filters["my_filter"] = my_filter

catalog = Catalog("components/", jinja_env=env)
```

--------------------------------

### Reference Static Files with url_for

Source: https://jx.scaletti.dev/docs/working/flask

Use Flask's `url_for` function to correctly reference static files like favicons. This example shows how to link a favicon in the layout component.

```jinja
{#def title #}

<!DOCTYPE html>
<html>
<head>
  <title>{{ title }}</title>
  <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">
  {{ assets.render_css() }}
</head>
<body>
  {{ content }}
  {{ assets.render_js() }}
</body>
</html>


```

--------------------------------

### Configure Assets in Jx

Source: https://jx.scaletti.dev/docs/from-jinjax

Jx simplifies asset management by removing middleware requirements and using a global assets object.

```jinja
{#css mypage.css #}
{#js mypage.js #}

<Layout title="My Page">
  {{ assets.render() }}
  ...
</Layout>
```

--------------------------------

### Relative Component Imports

Source: https://jx.scaletti.dev/docs/components

Demonstrates importing components using paths relative to the current file, suitable for tightly coupled components.

```jinja
{#import "./sibling.jinja" as Sibling #}
{#import "../parent/component.jinja" as Component #}
{#import "./subfolder/child.jinja" as Child #}


```

--------------------------------

### Multiple Elements with Split Attributes

Source: https://jx.scaletti.dev/docs/attrs

Shows how to apply attributes to different elements within a component. This example splits attributes, removing a card class from the main `attrs` and applying it to the outer div.

```jinja
{#def title #}

{% set card_class = attrs.get("card_class", "card") %}
{% do attrs.remove_class(card_class) %}

<div class="{{ card_class }}">
  <h3 {{ attrs.render() }}>{# Other attrs go on title #}
    {{ title }}
  </h3>
  <div class="body">
    {{ content }}
  </div>
</div>

```

--------------------------------

### Creating a Render Helper Function

Source: https://jx.scaletti.dev/docs/working/fastapi

Simplifies component rendering by wrapping the catalog call and HTMLResponse creation.

```python
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from jx import Catalog

app = FastAPI()
catalog = Catalog("components/", auto_reload=True)


def render(request: Request, component: str, status_code: int = 200, **context):
    """Render a Jx component with request context."""
    html = catalog.render(
        component,
        globals={"request": request},
        **context,
    )
    return HTMLResponse(html, status_code=status_code)


@app.get("/")
def home(request: Request):
    return render(request, "pages/home.jinja")


@app.get("/products")
def products(request: Request):
    products = get_products()
    return render(request, "pages/products.jinja", products=products)
```

--------------------------------

### Usage of Accordion Components

Source: https://jx.scaletti.dev/docs/working/alpinejs

Demonstrates how to import and nest accordion items within an accordion container.

```jinja
{#import "alpine-accordion.jinja" as Accordion #}
{#import "alpine-accordion-item.jinja" as AccordionItem #}

<Accordion>
  <AccordionItem id="q1" title="What is Alpine.js?">
    <p>Alpine.js is a lightweight JavaScript framework.</p>
  </AccordionItem>

  <AccordionItem id="q2" title="Why use it with Jx?">
    <p>It adds reactivity without a build step.</p>
  </AccordionItem>
</Accordion>
```

--------------------------------

### Component Definition with Attrs and Content

Source: https://jx.scaletti.dev/docs/attrs

This example defines a component that accepts a 'title' argument and renders its content within a div. All other attributes passed to the component are collected by 'attrs' and rendered using attrs.render().

```html
{#def title #}  {# 'title' is a declared argument #}

<div {{ attrs.render() }}>  {# Everything else becomes attrs #}
  <h2>{{ title }}</h2>
  {{ content }}
</div>

```

--------------------------------

### Serve package assets in Flask

Source: https://jx.scaletti.dev/docs/installable

Implement a route to serve static assets from a registered Jx package during development.

```python
from flask import Flask, send_from_directory
from jx import Catalog

app = Flask(__name__)

catalog = Catalog(
    "components/",
    auto_reload=app.debug,
    asset_resolver=lambda url, prefix: f"/pkg/{prefix}/{url}",
)
catalog.add_package("my_ui_kit", prefix="ui")

@app.route("/pkg/<prefix>/<path:filename>")
def serve_package_assets(prefix, filename):
    assets_dir = catalog.get_assets_folder(prefix)
    if assets_dir is None:
        abort(404)
    return send_from_directory(assets_dir, filename)
```

--------------------------------

### Inject Global Variables with Context Processors

Source: https://jx.scaletti.dev/docs/working/flask

Use Flask's context processors to make variables globally available in Jinja templates. This example injects 'site_name', 'current_year', and an 'is_authenticated' function.

```python
@app.context_processor
def inject_globals():
    return {
        "site_name": "My App",
        "current_year": 2026,
        "is_authenticated": lambda: session.get("user_id") is not None,
    }


```

--------------------------------

### Navigation Bar with Conditional User Links

Source: https://jx.scaletti.dev/docs/working/fastapi

An example Jinja2 navigation bar that displays user-specific links (e.g., profile, logout) or login/signup links based on whether the `user` object is present in the context.

```jinja
<nav>
  <a href="{{ url_for('home') }}">Home</a>

  {% if user %}
    <span>{{ user.email }}</span>
    <a href="{{ url_for('logout') }}">Logout</a>
  {% else %}
    <a href="{{ url_for('login') }}">Login</a>
  {% endif %}
</nav>

```
Tokens:
Raw