Basics

Let's start by creating your first Pulse application. We'll learn how to define a component and render HTML elements to the page.

Your First Component

A Pulse application is built from components. A component is a Python function that returns UI elements. Here's a simple example:

import pulse as ps

@ps.component
def home():
    return ps.div(
        ps.h1("Welcome to Pulse!", className="text-xl font-bold"),
        ps.p("You've created your first Pulse application."),
        className="p-4",
    )

app = ps.App([ps.Route("/", home)])

Let's break this down:

@ps.component - This decorator marks home as a Pulse component. Components can have their own state and lifecycle (more on this in later sections).
ps.div, ps.h1, ps.p - These are Pulse's HTML elements. They work just like their HTML counterparts but are created in Python.
ps.App - This creates your application and defines the routes. Here, the home component is rendered at the root path /.

How HTML Elements Work

Pulse provides all standard HTML elements as Python functions. The code above translates to this HTML:

<div class="p-4">
  <h1 class="text-xl font-bold">Welcome to Pulse!</h1>
  <p>You've created your first Pulse application.</p>
</div>

There are two ways to pass content to elements:

Positional Arguments (Children First)

Pass children as positional arguments, props as keyword arguments:

ps.h1("Hello World", className="text-xl")

This is convenient for simple elements with few children.

Bracket Syntax (Props First)

Use bracket syntax to keep props close to the element name:

ps.div(className="container p-4")[
    ps.h1("Title"),
    ps.p("Content here..."),
]

This resembles HTML more closely and is easier to read when you have many children.

A Note on Props

Pulse follows React conventions, which means some HTML attributes have different names:

class becomes className (to avoid conflict with Python's class keyword)
for becomes htmlFor
Event handlers use camelCase: onclick becomes onClick

These names will feel natural if you've used React. If not, don't worry - you'll get used to them quickly!

Running Your App

Save your code to a file (e.g., app.py) and run:

uv run pulse run app.py

Open the URL shown in your terminal (usually http://localhost:5173) to see your app in action.