```
:::
:::::
:::::::
::::: div home__section home__actions
[Get started ยป](/docs/){ .btn .btn--primary }
:::::
:::::: div bg
::::: div home__section home__spaghetti
## Say no to spaghetti templates
{ .left width="300" }
Your Python code should be easy to read and maintain.
Yet, template code often breaks even **the most basic standards**: long methods, deep nesting, and mysterious variables everywhere.
With components, **everything is clear**: you know where each piece lives, what states it can be in, and exactly what data it needs.
Try replacing all your templates with components, or just start with one page.
:::::
::::::
::::: div home__section home__better
## Why are components better?
Compared to Jinja's `{% include %}` or macros:
### โ Clear Dependencies
All imports are listed at the top; you can see exactly what a component uses.
### โ Composable
Components wrap content naturally using the `{{ content }}` variable or the slots feature, making them easy to nest and combine.
### โ Type-Safe
Required arguments are enforced; if you forget to pass a required prop, you get an error at load time, not render time.
### โ Testable
Each component can be tested independently with different props and content.
### โ Portable
With relative imports, you can move entire folders of related components without breaking anything.
### โ Encapsulated Assets
Each component can declare its own CSS and JS files, which are automatically collected and rendered.
:::::
----
---
title: Quickstart
id: quickstart
url: /docs/quickstart/
---
## Install Jx
Run the following command:
::: tab | Using "**pip**"
```bash
pip install jx
```
:::
::: tab | Using "**uv**"
```bash
uv add jx
```
:::
## Create a catalog
```python {title="app.py"}
from jx import Catalog
catalog = Catalog("components/")
```
## Create a component
Create a new folder for your components. Inside this folder create a new file called `card.jx` with the following content:
```html+jinja {title="components/card.jx"}
{#def title, url #}
```
## Use the component
```python {title="views.py"}
from .app import catalog
def dashboard_view():
return catalog.render("dashboard.jx")
```
```html+jinja {title="components/dashboard.jx"}
{#import "card.jx" as Card #}
We have the best trees
The best spades in the land
```
::: tab | Preview
```
:::
---
title: Catalog
description: Configuring and using the Jx Catalog
id: catalog
url: /docs/catalog/
---
The `Catalog` is the central manager for your components. It handles loading, caching, and rendering components from one or more folders.
## Basic Setup
```python
from jx import Catalog
catalog = Catalog("components/")
```
This creates a catalog that loads components from the `components/` folder.
## Constructor Options
```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
file_ext=".jx", # Component file extension
**globals # Global template variables
)
```
### `folder`
Optional path to a component folder. Shortcut for calling `add_folder()`:
```python
# These are equivalent:
catalog = Catalog("components/")
catalog = Catalog()
catalog.add_folder("components/")
```
### `file_ext`
The extension Jx uses to discover component files. Defaults to `.jx`.
Set it to keep a different convention (for example `.jinja` for older projects):
```python
catalog = Catalog("components/", file_ext=".jinja")
```
### `auto_reload`
When `True` (default), Jx checks if component files have changed and reloads them automatically. Great for development.
For production, set to `False` to skip file modification checks:
```python
catalog = Catalog("components/", auto_reload=False)
```
### `globals`
Variables available to all components:
```python
catalog = Catalog(
"components/",
site_name="My App",
current_year=2026,
debug=True,
)
```
```html+jinja title="components/footer.jx"
```
### `filters`
Custom Jinja2 filters:
```python
def format_price(value):
return f"${value:,.2f}"
def pluralize(count, singular, plural=None):
plural = plural or f"{singular}s"
return singular if count == 1 else plural
catalog = Catalog(
"components/",
filters={
"price": format_price,
"pluralize": pluralize,
}
)
```
```html+jinja
{{ product.price | price }}{{ count }} {{ count | pluralize("item") }}
```
### `tests`
Custom Jinja2 tests:
```python
def is_admin(user):
return user.role == "admin"
catalog = Catalog(
"components/",
tests={"admin": is_admin}
)
```
```html+jinja
{% if user is admin %}
Admin Panel
{% endif %}
```
### `extensions`
Extra Jinja2 extensions to load:
```python
catalog = Catalog(
"components/",
extensions=["jinja2.ext.i18n", "jinja2.ext.loopcontrols"]
)
```
Note: The `jinja2.ext.do` extension is always enabled (required for `attrs` manipulation).
### `jinja_env`
Use an existing Jinja2 environment instead of creating a new one:
```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)
```
This is useful when integrating with frameworks that provide their own Jinja environment.
### `asset_resolver`
Optional callback for transforming component asset URLs. Receives `(url, prefix)` and returns the resolved URL string. Only invoked for components whose prefix has a registered `assets` folder (see `add_folder`).
```python
def my_resolver(url, prefix):
return f"/static/{prefix}/{url}"
catalog = Catalog("components/", asset_resolver=my_resolver)
```
---
## Adding Folders
### `add_folder(path, prefix="", assets=None)`
Add a folder of components to the catalog:
```python
catalog = Catalog()
catalog.add_folder("components/")
catalog.add_folder("layouts/")
```
The optional `assets` parameter specifies a folder containing CSS/JS files for components in this folder. When set, the `asset_resolver` callback is used to transform asset URLs at render time (see [Installable Packages](/docs/installable/) for details).
Components are imported by their path relative to the folder:
```html+jinja
{#import "button.jx" as Button #}
{#import "forms/input.jx" as Input #}
```
### Using Prefixes
Prefixes namespace components, useful for third-party libraries:
```python
catalog.add_folder("components/")
catalog.add_folder("vendor/ui-kit/", prefix="ui")
catalog.add_folder("vendor/icons/", prefix="icons")
```
Import prefixed components with `@prefix/`:
```html+jinja
{#import "button.jx" as Button #}
{#import "@ui/modal.jx" as Modal #}
{#import "@icons/check.jx" as CheckIcon #}
```
### Multiple Folders, Same Prefix
If you add multiple folders with the same prefix (or no prefix), they're treated as one namespace. If both contain a component with the same path, the **first one added wins**:
```python
catalog.add_folder("my-components/") # Has button.jx
catalog.add_folder("fallback-components/") # Also has button.jx
# "button.jx" resolves to my-components/button.jx
```
---
## Rendering
### `render(relpath, globals=None, **kwargs)`
Render a component by its path:
```python
html = catalog.render("page.jx", title="Hello", user=current_user)
```
**Arguments:**
- `relpath` - Path to the component (e.g., `"pages/home.jx"`)
- `globals` - Dict of variables available to this component and all its imports
- `**kwargs` - Arguments passed directly to the component
```python
# Pass data as keyword arguments
html = catalog.render(
"user-profile.jx",
user=user,
posts=posts,
show_email=True,
)
# Or use globals for values needed by child components too
html = catalog.render(
"page.jx",
globals={"request": request, "csrf_token": token},
title="Dashboard",
)
```
### `render_string(source, globals=None, **kwargs)`
Render a component from a string (not a file):
```python
source = """
{#def name #}
Hello, {{ name }}!
"""
html = catalog.render_string(source, name="World")
#
Hello, World!
```
Useful for:
- Testing components
- Dynamic templates from a database
- Simple one-off renders
Note: String components can use absolute imports but not relative imports (no file path to resolve from).
---
## Introspection
### `list_components()`
Returns a list of all registered component paths:
```python
paths = catalog.list_components()
# ["button.jx", "card.jx", "forms/input.jx"]
```
### `get_signature(relpath)`
Returns a component's signature, including its arguments and metadata:
```python
sig = catalog.get_signature("button.jx")
```
Returns a dictionary with:
- `required` - dict of required argument names mapped to their type (or `None`)
- `optional` - dict of optional arguments mapped to `(default_value, type or None)`
- `slots` - tuple of slot names
- `css` - tuple of CSS file URLs
- `js` - tuple of JS file URLs
```python
sig = catalog.get_signature("modal.jx")
# {
# "required": {"title": str},
# "optional": {"size": ("md", str)},
# "slots": ("header", "footer"),
# "css": ("modal.css",),
# "js": ("modal.js",),
# }
```
### `collect_assets(output)`
Copies all registered package assets to an output folder. For each prefix that has a registered assets folder (see `add_folder`), files are copied to `
 }})