Halogen Guide

Halogen is a declarative, component-based UI library for PureScript that emphasizes type safety. In this guide you will learn the core ideas and patterns needed to write real-world applications in Halogen.

Here is a tiny Halogen app that lets you increment and decrement a counter:

module Main where

import Prelude

import Effect (Effect)
import Halogen as H
import Halogen.Aff as HA
import Halogen.HTML as HH
import Halogen.HTML.Events as HE
import Halogen.VDom.Driver (runUI)

main :: Effect Unit
main = HA.runHalogenAff do
  body <- HA.awaitBody
  runUI component unit body

data Action = Increment | Decrement

component =
  H.mkComponent
    { initialState
    , render
    , eval: H.mkEval $ H.defaultEval { handleAction = handleAction }
    }
  where
  initialState _ = 0

  render state =
    HH.div_
      [ HH.button [ HE.onClick \_ -> Decrement ] [ HH.text "-" ]
      , HH.div_ [ HH.text $ show state ]
      , HH.button [ HE.onClick \_ -> Increment ] [ HH.text "+" ]
      ]

  handleAction = case _ of
    Increment -> H.modify_ \state -> state + 1
    Decrement -> H.modify_ \state -> state - 1

You can paste this example (and any other full examples in this guide) into Try PureScript. We highly recommend doing this to explore the examples interactively! For example, try changing the buttons so they use the words "Increment" and "Decrement" instead of the symbols "+" and "-".

By default, Try PureScript will compile every time you make a change. You can also disable the auto-compile feature, which will cause Try PureScript to wait for you to click the "Compile" button to compile your Halogen application.

You can also create your own starter project with the official Halogen template. This template includes extra tools and scripts to help you get up and running with a full Halogen application.

Don't worry if this code is overwhelming at first -- when you've read the next few chapters of the guide you'll gain a solid understanding of how this component works and how to write your own.

How to Read This Guide

In this guide we'll explore the building blocks of Halogen apps: elements and components. When you understand these you can create complex apps from small, reusable pieces.

This is a step-by-step introduction to Halogen's main concepts. Each chapter builds on knowledge introduced in previous chapters, so we recommend reading through the guide in order.

Halogen is a PureScript library, and it assumes basic knowledge of PureScript concepts like functions, records, arrays, do notation, Effect, and Aff. It will also help if you understand the basics of HTML and the DOM. If you need a refresher, we recommend:

For PureScript: the PureScript Book and Jordan Martinez's PureScript Reference.
For HTML: the MDN introductions to HTML and DOM events.

Halogen Guide

Halogen Guide

How to Read This Guide

Table of Contents