Your first component

Components are the pieces you build a weft interface from. A button, a product card, a whole page: each is a component, and bigger components are made of smaller ones. If you've written React, you already know how they look, because a weft component is the same thing on the surface: a function that returns TSX. What happens underneath is different, and this page shows you both.

Components: pieces of UI you can reuse

On the web, HTML gives you tags such as <article>, <h1> and <ul> to build a page from:

<article>  <h1>My first component</h1>  <ol>    <li>Components: UI building blocks</li>    <li>Defining a component</li>    <li>Using a component</li>  </ol></article>

That markup is a page's structure: the article, its heading, a short table of contents. As a site grows, the same structures appear again and again: a card for every product, a row for every message, the same header on every page. A component lets you write a piece of markup once, with the logic that belongs to it, give it a name, and use it wherever you need it.

You can mix your own components with plain HTML tags and with components other people wrote. weft comes with warp, a set of ready components such as Button, Card and Input, and the demos on these pages use them alongside plain tags.

Defining a component

A component is a JavaScript function whose name starts with a capital letter and which returns markup. Here is one:

export default function Profile() {  return <img src="https://i.imgur.com/MK3eW3As.jpg" alt="Katherine Johnson" />}

You build it in three steps.

Step 1: Export the component

export default makes the function the file's main export, so another file can import it. A route file in src/routes must export its page this way. The next page, Importing and exporting components, covers exports in full.

Step 2: Define the function

function Profile() { } defines a function called Profile.

Step 3: Add the markup

The function returns <img /> with src and alt attributes. It looks like HTML, but it is TSX: markup inside TypeScript. The return can fit on one line, or span several inside parentheses:

export default function Profile() {  return (    <div>      <img src="https://i.imgur.com/MK3eW3As.jpg" alt="Katherine Johnson" />    </div>  )}

Using a component

Once Profile exists, other components can use it. Here Gallery uses it three times, with a different name and field each time. Values you hand a component like this are called props, and Passing props covers them.

What the browser sees

Notice the difference in case:

• <figure> and <strong> are lowercase, so they are HTML tags.
• <Profile /> starts with a capital P, so it is the Profile component.

Profile itself contains more HTML: a <figure>, a <span>, a <figcaption>. In the end the browser sees only HTML elements. There is no <Profile> element in the page; the component has done its work and left its markup behind.

Nesting and organising components

Components are ordinary functions, so you can keep several in one file. That's handy while they are small and related. When a file gets crowded, move a component to its own file and import it. Because Profile is used inside Gallery, Gallery is called the parent and Profile the child: this parent and child relationship is the shape of your UI, and Your UI as a tree looks at it closely.

TSX is markup with expressions

Inside TSX, curly braces open a window back into JavaScript. Any expression can go there: {props.name}, a ternary, a function call. Attributes take expressions the same way:

export function Greeting(props: { name: string }) {  return <p class="greeting">Hello, {props.name}.</p>}

Both class and className work, and so do React's camelCase names such as tabIndex and htmlFor. The rules of TSX have their own page, Writing markup with TSX, and braces get theirs in JavaScript in TSX with braces.

The body runs once

This is the one big difference from React. weft calls a component function once, when that part of the page first appears, and never calls it again. When a value changes later, nothing re-renders: the compiler has already wired each {expression} and each attribute to the DOM node it fills, so that one node is written and nothing else runs.

That's why there are no hook rules and no dependency arrays in weft. Code in the body runs once, top to bottom, and sets things up. The live parts are the expressions in your markup, plus anything you put in derived or watch.

It also means that a value computed in the body is computed once:

import { derived } from '@weft-js/core'export function Total(props: { price: number; qty: number }) {  // const total = props.price * props.qty  would be worked out once and never change: the compiler reports W001.  const total = derived(() => props.price * props.qty)  return <p>Total: {total.value}</p>}

Work values out in the markup itself ({props.price * props.qty}) or with derived (see Derived values). If you compute from a prop or a piece of state in the body, the compiler stops you with W001 and offers the derived version as a fix. Components run once is the page on this idea, with the mistakes it catches.

Recap

• A component is a function whose name starts with a capital letter and which returns TSX.
• Use it as a tag, <Profile />, inside other components. Define every component at the top level of a file.
• export default makes it the file's main export, and a route file in src/routes exports its page that way.
• The body runs once. {expressions} and attributes in TSX stay up to date by themselves.
• Compute in the markup or with derived, not in the body (W001).

Try it