Getting started

This tutorial assumes you have basic knowledge of ClojureScript. Throughout the tutorial, we'll use UIx and React names interchangeably, since most of UIx is basically React itself. For concepts specific to UIx, we'll make sure to point them out.

Creating and nesting components

User interface built with React is a tree of components. Each component describes its internal view structure, appearance and behavior. In UIx, components are created using the defui macro. And view structure consists of elements, which are created using the $ macro.

Writing markup

HTML elements use HyperScript syntax to include id and class names as a part of tag name. Additionally, when creating div element with either id or class name the :div keyword can be omitted: :div.button is the same as :.button. Writing class names as keywords in HyperScript syntax is preferred over strings in props map, because most editors are able to autocomplete keywords.

Displaying data

Any UIx element can display content by passing it as a child. The content can be a string, number, or another element.

Rendering lists

A list of HTML elements is rendered by simply passing a sequence of elements as children. Usually the sequence is generated by mapping over a collection of data. Each element in the sequence has to have a unique :key attribute. The key should be derived from data that uniquely identifies the element. The key helps React to efficiently update the DOM.

Responding to events & updating the screen

React components can respond to user input by defining event handlers. The name of the event handler in UIx is a keyword in kebab-case, and the handler function is passed as a prop. See :on-click in the example below.

To update data and display it on the screen, components use state. State is a value that can change over time. In React, state is managed using hooks. Hooks are side-effecting functions that let you use state and other React features. In UIx state is managed using the use-state hook. The hook takes an initial value and returns a tuple containing the current value and a function to update it.

Using Hooks & sharing data between components

Functions starting with use- are called Hooks. use-state is a Hook that lets you add state to React components. Hooks are not like normal functions, they can only be called from React components and only from the top level of the component. Calling them conditionally or in loops is not allowed. If you want to use a Hook conditionally, extract a new component and put it there.

In the previous example each button has its own state. To share state between components, the state should be lifted up to the parent component. The parent component can then pass the state and the function to update it as props to the child components. The data passed to the child components is called props. When you press a button, the state is updated in the parent component, and the new state is passed to the child components.

Now you know the basics of UIx and React! Head over to Quick Start section to learn how to set up a project and start building your first app. You may also want to checkout recipes page for more examples.