elementary - GitLite

KO | EN

gitlite — search

#javascript #python #go #machine-learning #deep-learning #linux #macos #windows #kubernetes #vue #pytorch #mcp #openai #open-source

elementary

(★ 405)

A modern and efficient HTML rendering library - inspired by SwiftUI, built for the web.

파일 탐색기

최종 버전 다운로드 (.zip)

- - api-breakage.yml
  - ci-embedded.yaml
  - ci-examples.yaml
  - ci.yaml
  - format.yaml
- .gitignore
- Package.swift
- - Package.swift
  - README.md
  - swift-dev
- - AsyncRenderingTests.swift
  - AttributeRenderingTests.swift
  - ClassAndStyleRenderingTests.swift
  - CompositionRenderingTest.swift
  - ContentBuilderTests.swift
  - EnvironmentRenderingTests.swift
  - FormattedRenderingTest.swift
  - SendableAnyHTMLBox.swift
  - StyleKeyValuePairsTests.swift
  - SVGRenderingTests.swift
  - TagRenderingTests.swift
  - TextRenderingTests.swift
  - TupleRenderingTests.swift
  - Utilities.swift
- embedded-wasm.toolset.json
.gitignore
.spi.yml
.swift-format
LICENSE
Package.swift
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Elementary: HTML Templating in Pure Swift

**A modern and efficient HTML rendering library - inspired by SwiftUI, built for the web.**

[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Felementary-swift%2Felementary%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/elementary-swift/elementary) [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Felementary-swift%2Felementary%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/elementary-swift/elementary)

> [!NOTE]
>
> For running Swift apps in the browser, check out  **[ElementaryUI](https://elementary.codes/)**.
> 
>   <a href="https://elementary.codes">
>    <img src="https://elementary.codes/og-image.png" width="400px" alt="Elementary Logo">
>  </a>

[Examples](#play-with-it) | [Motivation](#motivation-and-other-packages) | [Discussion](https://github.com/elementary-swift/elementary/discussions)

```swift
struct MainPage: HTMLDocument {
    var title = "Elementary"

var head: some HTML {
        meta(.name(.description), .content("Typesafe HTML in modern Swift"))
    }

var body: some HTML {
        main {
            h1 { "Features" }

FeatureList(features: [
                "HTML in pure Swift",
                "SwiftUI-inspired composition",
                "Lightweight and fast",
                "Framework agnostic and unopinionated",
            ])

a(.href("https://github.com/elementary-swift/elementary"), .class("fancy-style")) {
                "Learn more"
            }
        }
    }
}

struct FeatureList: HTML {
    var features: [String]

var body: some HTML {
        ul {
            for feature in features {
                li { feature }
            }
        }
    }
}
```

## Use it

Add the dependency to `Package.swift`
```swift
.package(url: "https://github.com/elementary-swift/elementary.git", from: "0.6.0")
.product(name: "Elementary", package: "elementary")
```

Integration with [Hummingbird](https://github.com/hummingbird-community/hummingbird-elementary)
```swift
.package(url: "https://github.com/hummingbird-community/hummingbird-elementary.git", from: "0.3.0")
.product(name: "HummingbirdElementary", package: "hummingbird-elementary")
```

Integration with [Vapor](https://github.com/vapor-community/vapor-elementary)
```swift
.package(url: "https://github.com/vapor-community/vapor-elementary.git", from: "0.1.0")
.product(name: "VaporElementary", package: "vapor-elementary")
```

## Play with it

Check out the [Hummingbird + Tailwind example app](https://github.com/elementary-swift/elementary/tree/main/Examples/HummingbirdDemo).

For a demo of [ElementaryHTMX](https://github.com/elementary-swift/elementary-htmx), see this [Hummingbird + HTMX Demo](https://github.com/elementary-swift/elementary-htmx/tree/main/Examples/HummingbirdDemo).

For a Vapor example, see the [Vapor + HTMX Demo](https://github.com/elementary-swift/elementary-htmx/tree/main/Examples/VaporDemo).

## Lightweight and fast

Elementary renders straight to text, optimized for serving generated HTML from a [Hummingbird](https://github.com/hummingbird-project/hummingbird) or [Vapor](https://vapor.codes/) server app.

Any type conforming to `HTML` can be rendered individually, ideal for testing or for sending fragments with [htmx](https://github.com/elementary-swift/elementary-htmx).

The default rendering mechanism produces chunks of HTML for efficient response streaming, so the browser can start loading a page while the server is still producing the rest of it. Swift concurrency is used to handle back pressure, so you your memory footprint stays low even for large pages.

```swift
// Stream HTML, optimized for responsiveness and back pressure-aware
try await MainPage().render(into: responseStreamWriter)
```

Alternatively, you can simply collect the rendered HTML in a string.

```swift
let html: String = div(.class("pretty")) { "Hello" }.render()
// <div class="pretty">Hello</div>

let fragment: String = FeatureList(features: ["Anything conforming to HTML can be rendered"]).render()
// <ul><li>Anything conforming to HTML can be rendered</li></ul>

// For testing purposes, there is also a formatted version
print(
    div {
        p(.class("greeting")) { "Hi mom!" }
        p { "Look how pretty." }
    }.renderFormatted()
)

// <div>
//   <p class="greeting">Hi mom!</p>
//   <p>Look how pretty.</p>
// </div>
```

Elementary has zero dependencies (not even Foundation) and does not use runtime reflection or existential containers (there is not a single `any` in the code base).

By design, it does not come with a layout engine, reactive state tracking, or built-in CSS styling: it just renders HTML.

## Clean and composable

Structure your HTML with a SwiftUI-inspired composition API.

```swift
struct List: HTML {
    var items: [String]
    var importantIndex: Int

var body: some HTML {
        // conditional rendering
        if items.isEmpty {
            p { "No items" }
        } else {
            ul {
                // list rendering
                for (index, item) in items.enumerated() {
                    // seamless composition of elements
                    ListItem(text: item, isImportant: index == importantIndex)
                }
            }
        }
    }
}

struct ListItem: HTML {
    var text: String
    var isImportant: Bool = false

var body: some HTML {
        // conditional attributes
        li { text }
            .attributes(.class("important"), when: isImportant)
    }
}
```

## First class attribute handling

Elementary utilizes Swift's powerful generics to provide an attribute system that knows what goes where. Every element knows which Tag it is for.

As in HTML, attributes go right after the "opening tag".

```swift
// staying close to HTML syntax really helps
div(.data("hello", value: "there")) {
    a(.href("/swift"), .target(.blank)) {
        img(.src("/swift.png"))
        span(.class("fancy")) { "Click Me" }
    }
}
```

Attributes can also be altered by using the modifier syntax, this allows for easy handling of conditional attributes.

```swift
div {
    p { "Hello" }
        .attributes(.id("maybe-fancy"))
        .attributes(.class("fancy"), when: isFancy)
}
```

By exposing the tag type of `body`, attributes will fall through and be applied correctly.

```swift
struct Button: HTML {
    var text: String

// by exposing the HTMLTag type information...
    var body: some HTML<HTMLTag.input> {
        input(.type(.button), .value(text))
    }
}

div {
    // ... Button will know it really is an <input> element ...
    Button(text: "Hello")
        .attributes(.autofocus) // ... and pass on any attributes
}
```

As a sensible default, _class_ and _style_ attributes are merged (with a blank space or semicolon respectively). All other attributes are overwritten by default.

## Seamless async support

Elementary supports Swift Concurrency in HTML content. Simply `await` something inside your HTML, while the first bytes are already flying towards the browser.

```swift
div {
    let text = await getMyData()
    p { "This totally works: \(text)" }
    MyComponent()
}

struct MyComponent: HTML {
    var body: some HTML {
        AsyncContent {
            "So does this: \(await getMoreData())"
        }
    }
}
```

By using the `AsyncForEach` element, any `AsyncSequence` can be efficiently rendered straight to HTML.

```swift
ul {
    // the full result never needs to be stored in memory...
    let users = try await db.users.findAll()
    // ...as each async sequence element...
    AsyncForEach(users) { user in
        // ...is immediately streamed out as HTML
        li { "\(user.name) \(user.favoriteProgrammingLanguage)" }
    }
}
```

## Enviroment values

Elementary utilizes `TaskLocal`s to provide a light-weight environment system.

```swift
enum MyValues {
    // task-locals act as keys, ...
    @TaskLocal static var userName = "Anonymous"
}

struct MyComponent: HTML {
    // ... their values can be accessed ...
    @Environment(MyValues.$userName) var userName

var body: some HTML {
        p { "Hello, \(userName)!" }
    }
}

div {
    // ... and provided in a familiar way
    MyComponent()
        .environment(Values.$userName, "Drax the Destroyer")
}
```

### Contributing

The list of built-in attributes is far from complete, but adding them is really simple (and can be done in external packages as well).

Feel free to open a PR with additional attributes that are missing from the model.

<p align="center">
  <i>Thank you to everyone supporting this open‑source project financially.
  <br>Please consider joining them by <a href="https://github.com/sponsors/sliemeobn" target="_blank" rel="noopener">sponsoring ElementaryUI</a>.</i>
  <a href="https://elementary.codes#sponsors">
  <picture>
    <source media="(width <= 600px)" srcset="https://elementary.codes/sponsors/sponsors-400.svg" />
    <source media="(width <= 800px)" srcset="https://elementary.codes/sponsors/sponsors-600.svg" />
    <img src="https://elementary.codes/sponsors/sponsors-800.svg" alt="Sponsors" />
  </picture>
  </a>
</p>

## Motivation and other packages

[Plot](https://github.com/JohnSundell/Plot), [HTMLKit](https://github.com/vapor-community/HTMLKit), and [Swim](https://github.com/robb/Swim) are all excellent packages for doing a similar thing.

My main motivation for Elementary was to create an experience like these ([Swift Forums post](https://forums.swift.org/t/elementary-a-modern-and-efficient-html-rendering-library-inspired-by-swiftui-built-for-the-web/72647) for more context), but

- stay true to HTML tag names and conventions (including the choice of lowercase types)
- avoid allocating an intermedate structure and go straight to streaming HTML
- using generics to stay away from allocating a ton of lists of existential `any`s
- have a list of attributes go before the content block
- provide _attribute fallthrough_ and merging
- zero dependencies on other packages

[Tokamak](https://github.com/TokamakUI/Tokamak) is an awesome project and very inspiring. It can produce HTML, but it's main focus is on a very different beast. Check it out!

[swift-html](https://github.com/pointfreeco/swift-html) and [swift-dom](https://github.com/tayloraswift/swift-dom) will produce HTML nicely, but they use a different syntax for composing HTML elements.

---

*SwiftUI is a trademark of Apple Inc. This project is not affiliated with or connected to Apple in any way.*