HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Modulelucid-2.11.20230408Haskell2010

Lucid

Clear to write, read and edit DSL for writing HTML

See Lucid.Html5 for a complete list of Html5 combinators. That module is re-exported from this module for your convenience.

See Lucid.Base for lower level functions like makeElement, makeAttribute, termRaw, etc.

To convert html to the lucid DSL, use the (experimental) program lucid-from-html which may eventually be integrated into lucid itself.

  • 3 types
  • 3 classes
  • 8 values

Intro

5 declarations

HTML terms in Lucid are written with a postfix ‘_’ to indicate data rather than code. Some examples:

p_, class_, table_, style_

Note: If you're testing in the REPL you need to add a type annotation to indicate that you want HTML. In normal code your top-level declaration signatures handle that.

For GHCi:

:set -XOverloadedStrings -XExtendedDefaultRules@
import Lucid

In a module: {-# LANGUAGE OverloadedStrings, ExtendedDefaultRules #-}

Plain text is written like this, and is automatically escaped:

Example1 expression
"123 < 456" :: Html ()123 &lt; 456

Except some elements, like script_:

Example1 expression
script_ "alert('Hello!' > 12)" :: Html ()<script>alert('Hello!' > 12)</script>

Elements nest by function application:

Example1 expression
table_ (tr_ (td_ (p_ "Hello, World!"))) :: Html ()<table><tr><td><p>Hello, World!</p></td></tr></table>

Elements are juxtaposed via monoidal append (remember to import Data.Monoid):

Example1 expression
p_ "hello" <> p_ "sup" :: Html ()<p>hello</p><p>sup</p>

Or monadic sequencing:

Example1 expression
div_ (do p_ "hello"; p_ "sup") :: Html ()<div><p>hello</p><p>sup</p></div>

Attributes are set by providing an argument list:

Example1 expression
p_ [class_ "brand"] "Lucid Inc" :: Html ()<p class="brand">Lucid Inc</p>
Example1 expression
p_ [data_ "zot" "foo",checked_] "Go!" :: Html ()<p data-zot="foo" checked>go</p>

Attribute and element terms are not conflicting:

Example1 expression
style_ [style_ "inception"] "Go deeper." :: Html ()<style style="inception">Go deeper.</style>

Here is a fuller example of Lucid:

table_ [rows_ "2"]
       (tr_ (do td_ [class_ "top",colspan_ "2",style_ "color:red"]
                    (p_ "Hello, attributes!")
                td_ "yay!"))

Elements (and some attributes) are variadic and overloaded, see the Term class for more explanation about that.

For proper rendering you can easily run some HTML immediately with:

Example1 expression
renderText (p_ "Hello!")> "<p>Hello!</p>"
Example1 expression
renderBS (p_ [style_ "color:red"] "Hello!")"<p style=\"color:red\">Hello!</p>"

For ease of use in GHCi, there is a Show instance, as demonstrated above.

Running

3 declarations

If the above rendering functions aren't suited for your purpose, you can run the monad directly and use the more low-level blaze Builder, which has a plethora of output modes in Blaze.ByteString.Builder.

valueexecHtmlT
  1. :: Monad m
  2. => HtmlT m a

    The HTML to generate.

  3. -> m Builder

    The a is discarded.

#

Build the HTML. Analogous to execState.

You might want to use this is if you want to do something with the raw Builder. Otherwise for simple cases you can just use renderText or renderBS.

valueevalHtmlT
  1. :: Monad m
  2. => HtmlT m a

    HTML monad to evaluate.

  3. -> m a

    Ignore the HTML output and just return the value.

#

Evaluate the HTML to its return value. Analogous to evalState.

Use this if you want to ignore the HTML output of an action completely and just get the result.

For using with the Html type, you'll need runIdentity e.g.

Example1 expression
runIdentity (evalHtmlT (p_ "Hello!"))()
valuerunHtmlT :: HtmlT m a -> m (Seq Attribute -> Builder, a)
#

This is the low-level way to run the HTML transformer, finally returning an element builder and a value. You can pass mempty for this argument for a top-level call. See evalHtmlT and execHtmlT for easier to use functions.

Types

3 declarations
typetype Html = HtmlT Identity
#

Simple HTML builder type. Defined in terms of HtmlT. Check out that type for instance information.

Simple use-cases will just use this type. But if you want to transformer over Reader or something, you can go and use HtmlT.

newtypenewtype HtmlT (m :: Type -> Type) a
#

A monad transformer that generates HTML. Use the simpler Html type if you don't want to transform over some other monad.

Don't rely on the internal representation of this type. Use the monad and functor classes.

Instances22MonadTrans, MFunctor, MonadError, MonadReader, MonadState, MonadWriter, …
datadata Attribute
#

A simple attribute. Don't use the constructor, use makeAttribute. Attributes are case sensitive, so if you want attributes to be merged properly, use a single case representation.

Instances7Eq, Show, Hashable, Term, TermRaw, …

Classes

3 declarations

To support convenient use of HTML terms, HTML terms are overloaded. Here are the following types possible for an element term accepting attributes and/or children:

p_ :: Term arg result => arg -> result
p_ :: Monad m => [Attribute] -> HtmlT m () -> HtmlT m ()
p_ :: Monad m => HtmlT m () -> HtmlT m ()

The first is the generic form. The latter two are the possible types for an element.

Elements that accept no content are always concrete:

input_ :: Monad m => [Attribute] -> HtmlT m ()

And some elements share the same name as attributes, so you can also overload them as attributes:

style_ :: TermRaw arg result => arg -> result
style_ :: Monad m => [Attribute] -> Text -> HtmlT m ()
style_ :: Monad m => Text -> HtmlT m ()
style_ :: Text -> Attribute
classclass Term arg result | result -> arg where
#

Used to construct HTML terms.

Simplest use: p_ = term "p" yields p_.

Very overloaded for three cases:

  • The first case is the basic arg of [(Text,Text)] which will return a function that wants children.

  • The second is an arg which is HtmlT m (), in which case the term accepts no attributes and just the children are used for the element.

  • Finally, this is also used for overloaded attributes, like style_ or title_. If a return type of (Text,Text) is inferred then an attribute will be made.

The instances look intimidating but actually the constraints make it very general so that type inference works well even in the presence of things like OverloadedLists and such.

Methods

  • term :: Text -> arg -> result

    Used for constructing elements e.g. term "p" yields p_.

  • termWith :: Text -> [Attribute] -> arg -> result

    Use this if you want to make an element which inserts some pre-prepared attributes into the element.

Instances3Term
  • Term Text AttributeDefined in lucid-2.11.20230408 · Lucid.Base

    Some terms (like style_, title_) can be used for attributes as well as elements.

  • (Applicative m, f ~ HtmlT m a) => Term [Attribute] (f -> HtmlT m a)Defined in lucid-2.11.20230408 · Lucid.Base

    Given attributes, expect more child input.

  • Applicative m => Term (HtmlT m a) (HtmlT m a)Defined in lucid-2.11.20230408 · Lucid.Base

    Given children immediately, just use that and expect no attributes.

classclass ToHtml a where
#

Can be converted to HTML.

Methods

Instances6ToHtml
  • ToHtml ByteStringDefined in lucid-2.11.20230408 · Lucid.Base

    This instance requires the ByteString to contain UTF-8 encoded text, for the toHtml method. The toHtmlRaw method doesn't care, but the overall HTML rendering methods in this module assume UTF-8.

  • ToHtml ByteStringDefined in lucid-2.11.20230408 · Lucid.Base

    This instance requires the ByteString to contain UTF-8 encoded text, for the toHtml method. The toHtmlRaw method doesn't care, but the overall HTML rendering methods in this module assume UTF-8.

  • ToHtml StringDefined in lucid-2.11.20230408 · Lucid.Base
  • ToHtml TextDefined in lucid-2.11.20230408 · Lucid.Base
  • ToHtml TextDefined in lucid-2.11.20230408 · Lucid.Base
  • (a ~ (), m ~ Identity) => ToHtml (HtmlT m a)Defined in lucid-2.11.20230408 · Lucid.Base
classclass With a where
#

With an element use these attributes. An overloaded way of adding attributes either to an element accepting attributes-and-children or one that just accepts attributes. See the two instances.

Methods

  • with :: a -> [Attribute] -> a

    With the given element(s), use the given attributes.

Instances2With
  • Functor m => With (HtmlT m a)Defined in lucid-2.11.20230408 · Lucid.Base

    For the contentless elements: br_

  • Functor m => With (HtmlT m a -> HtmlT m a)Defined in lucid-2.11.20230408 · Lucid.Base

    For the contentful elements: div_

Re-exports

0 declarations

module Lucid.Html5