Merenda is a desktop GUI toolkit written in Nim, inspired by Cocoa and OpenStep.
It gives you buttons, text editors, tables, menus, and layouts for building desktop
apps, with themes you can change to suit your app. Its public module is called
NimKit: import merenda/nimkit.
The project is under active development, targeting macOS, Linux, FreeBSD, and Windows. Kosmo, a code editor built with Merenda, is a way to try it without writing any code.
Merenda draws its own controls, so you can use the same theme across platforms. Choose a familiar macOS look, glossy Aqua buttons, or something more colorful. DarkBSD is the default.
You'll need Nim 2.2.6 or newer, a C compiler, Git, and Atlas to install the Nim dependencies. On Linux and FreeBSD, you'll also need the system libraries for your windowing and graphics backend; Merenda uses Siwin for windows and FigDraw for rendering.
To try the examples, clone the repository and run the controls showcase:
git clone https://github.com/elcritch/merenda.git
cd merenda
atlas install -tuk
nim r examples/controls_showcase.nimThe showcase lets you try the controls together in one window. To see another
theme, run it with NIMKIT_THEME set (in a POSIX shell):
NIMKIT_THEME=macos nim r examples/controls_showcase.nim
NIMKIT_THEME=aqua nim r examples/controls_showcase.nimTo use Merenda in your own project, add this dependency to your .nimble file
and run atlas install -tuk from that project:
requires "https://github.com/elcritch/merenda"Build your app with threads enabled and ARC or ORC, for example
nim r --threads:on --mm:arc main.nim. The examples in this repository already
have those settings.
FigDraw is compiled into the application. Merenda's experimental
useNativeDynlib mode and build_dynlib task have been removed; omit
-d:useNativeDynlib from existing build commands.
Build a resource document with Tekton's widget palette, property inspector, and live preview. Add layout guides and constraints, pin views to their parent, undo changes, and save the result for your Merenda app. Use Interact to try controls in the preview.
nim r src/merenda/tekton.nim
# Or open an existing interface:
nim r src/merenda/tekton.nim path/to/interface.cborSee Tekton's authoring workflow for supported resources and how to load the saved interface in your app.
A window, a label, and an application loop:
import merenda/nimkit
let
app = sharedApplication()
window = newWindow("Hello", frame = rect(100, 100, 360, 180))
root = newView()
greeting = newTitleLabel("Hello, Merenda!")
root.addSubview(greeting)
greeting.pinEdges(
toGuide = root.contentLayoutGuide(insets(24.0)),
edges = {leLeft, leTop, leRight},
)
app.runWindow(window, root)Save this as examples/greeting.nim in your checkout and run
nim r examples/greeting.nim.
Here's a counter. A stack view arranges the controls, and the button's action updates the label.
import merenda/nimkit
import sigils/selectors
let
app = sharedApplication()
window = newWindow("Counter", frame = rect(100, 100, 320, 220))
root = newView()
layout = newStackView(laVertical)
label = newStatusLabel("Clicked 0 times")
button = newButton("Click")
clickAction = actionSelector("counterClicked")
var clicks = 0
proc onClick(sender: DynamicAgent) =
if not sender.isNil:
inc clicks
label.text = "Clicked " & $clicks & " times"
button.target = newActionTarget(clickAction, onClick)
button.action = clickAction
layout.spacing = 12.0
layout.alignment = svaFill
layout.addArrangedSubview(label, button)
root.addSubview(layout)
layout.pinEdges(
toGuide = root.contentLayoutGuide(insets(44.0, 44.0, 0.0, 44.0)),
edges = {leLeft, leTop, leRight},
)
app.runWindow(window, root)This is examples/quick_start.nim. Run it with:
nim r examples/quick_start.nimNimKit's larger controls handle more of the work for you. This app opens a Markdown file with selectable text, links, code blocks, tables, and images. The view handles scrolling and layout as you resize the window.
import std/os
import merenda/nimkit
let
path = absolutePath(paramStr(1))
app = sharedApplication()
window = newWindow(path.extractFilename(), frame = rect(120, 80, 820, 700))
root = newView()
viewer = newMarkdownView(readFile(path), imageBasePath = path.parentDir)
root.addSubview(viewer)
viewer.pinEdges(toGuide = root.contentLayoutGuide(insets(20.0)))
app.runWindow(window, root, viewer)Save it as examples/reader.nim, then run
nim r examples/reader.nim README.md. It expects a readable file path.
For a version with a built-in sample document, run:
nim r examples/markdown_viewer_demo.nim README.mdThat is the kind of efficiency NimKit aims for: you write the app's behavior, while the controls take care of text selection, focus, drawing, and layout. For an app with more interaction, try the to-do list or its table-based version, which adds row selection and drag reordering.
For a small app, MVP doesn't need a class hierarchy. Here, tasks holds the
model data in an ArrayController, the table and button are the view, and
markDone acts as the presenter. Select a row and click Mark done: the
presenter updates the model and refreshes the table.
import merenda/nimkit
import sigils/selectors
let
app = sharedApplication()
window = newWindow("Tasks", frame = rect(100, 100, 460, 320))
root = newView()
table = newTableView(frame = rect(24, 24, 412, 200))
doneButton = newButton("Mark done", frame = rect(24, 244, 140, 32))
tasks = newArrayController(columns = [
modelColumn("task", "Task", "task", 260.0),
modelColumn("state", "State", "state", 100.0),
])
for index, title in ["Write release notes", "Try the demo"]:
tasks.addItem(modelItem($index, fields = [
modelField("task", toObj(title)),
modelField("state", toObj("To do")),
]))
table.bindTableView(tasks)
table.selectionMode = tsmSingle
# The presenter turns a user action into a model update.
proc markDone(sender: DynamicAgent) =
discard sender
let selected = tasks.selectionController().selectedIdentifier()
if selected.len > 0:
tasks.setValue(selected, "state", toObj("Done"))
table.reloadData()
let doneAction = actionSelector("markTaskDone")
doneButton.target = newActionTarget(doneAction, markDone)
doneButton.action = doneAction
root.addSubview(table)
root.addSubview(doneButton)
app.runWindow(window, root, table)Save this as examples/tasks_mvp.nim and run nim r examples/tasks_mvp.nim.
The table binding supplies the columns and row values, so you only write the
action specific to your app. For a larger version, see the
table-based to-do app or the
model controller examples.
Sigils protocols let you attach methods to an individual object, even when its
type comes from a library. Here, an ordinary View gets a custom drawing method.
Click Inspect layout to replace that method with one that displays the
view's dimensions; click again to restore the preview.
import merenda/nimkit
import sigils/selectors
protocol PreviewDrawing of ViewDrawingProtocol:
method draw(view: View, context: DrawContext) =
context.addRectangle(view.bounds, fill(color(0.18, 0.32, 0.55)))
context.addText(view.bounds, "Design preview", color(1, 1, 1), taCenter)
protocol LayoutDrawing of ViewDrawingProtocol:
method draw(view: View, context: DrawContext) =
context.addRectangle(view.bounds, fill(color(0.12, 0.22, 0.24)))
let size = view.bounds.size
context.addText(
view.bounds, $size.width & " x " & $size.height, color(1, 1, 1), taCenter
)
let
app = sharedApplication()
window = newWindow("Dynamic drawing", frame = rect(100, 100, 420, 260))
root = newView()
preview = newView(frame = rect(24, 24, 372, 140))
button = newButton("Inspect layout", frame = rect(24, 188, 160, 32))
inspectAction = actionSelector("toggleLayoutDrawing")
preview.withProtocol(PreviewDrawing)
var inspecting = false
proc toggleLayout(sender: DynamicAgent) =
discard sender
inspecting = not inspecting
if inspecting:
preview.withProtocol(LayoutDrawing)
else:
preview.withProtocol(PreviewDrawing)
preview.needsDisplay = true
button.target = newActionTarget(inspectAction, toggleLayout)
button.action = inspectAction
root.addSubview(preview)
root.addSubview(button)
app.runWindow(window, root)Save this as examples/protocol_drawing.nim and run
nim r examples/protocol_drawing.nim.
Both implementations are compiled Nim code with typed View and DrawContext
arguments. NimKit calls the drawing protocol, and Sigils dispatches to the method
currently installed on preview. Replacing it leaves other views alone and
keeps this view's identity, layout, and place in the window intact.
This is useful for adding diagnostics, swapping rendering strategies, or customizing a library object without introducing a subclass for every variation. The same pattern works for view controller loading and table delegates.
An animationGroup turns ordinary property assignments into a coordinated
animation. These two panels slide together over 800 ms with linear motion.
Next slides to the details; Back reverses the trip.
import merenda/nimkit
import sigils/selectors
let
app = sharedApplication()
window = newWindow("Carousel", frame = rect(100, 100, 420, 260))
root = newView()
viewport = newView(frame = rect(24, 24, 372, 140))
first = newGroupBox("Welcome", frame = rect(0, 0, 372, 140))
second = newGroupBox("Details", frame = rect(372, 0, 372, 140))
button = newButton("Next", frame = rect(24, 188, 160, 32))
slideAction = actionSelector("slidePanels")
first.contentView = newLabel("Your first panel.")
second.contentView = newLabel("A little more information.")
viewport.clipsToBounds = true
var showingDetails = false
proc finishSlide(button: Button) {.slot.} =
button.enabled = true
proc slidePanels(sender: DynamicAgent) =
discard sender
if button.enabled:
button.enabled = false
showingDetails = not showingDetails
button.title = if showingDetails: "Back" else: "Next"
let size = viewport.bounds.size
let offset =
if showingDetails:
-size.width
else:
0.0'f32
let slide = animationGroup(duration = 800.ms, curve = acLinear):
first.frame = rect(offset, 0, size.width, size.height)
second.frame = rect(offset + size.width, 0, size.width, size.height)
slide.connect(finished, button, finishSlide)
discard app.startAnimation(slide)
button.target = newActionTarget(slideAction, slidePanels)
button.action = slideAction
viewport.addSubview(first)
viewport.addSubview(second)
root.addSubview(viewport)
root.addSubview(button)
app.runWindow(window, root)Run the carousel example with
nim r examples/carousel_demo.nim. The viewport clips the panels as they move,
and the animation's finished signal enables the button for the next transition.
For more, see property animations and sequences.
A standard Box can blur the content behind its rounded bounds through FigDraw.
Its child controls stay sharp, and its fill follows the active theme:
let overlay = newBox(frame = rect(24, 24, 320, 96))
overlay.addStyleClass(PopoverBoxStyleClass)
overlay.backdropBlurRadius = 20
overlay.backdropTintOpacity = 0.78
overlay.addContentSubview(newTextField("Search"))
root.addSubview(overlay)Set backdropBlurRadius to zero to restore the ordinary box fill.
backdropTintOpacity controls the themed tint over the blurred content, from
zero to one. This effect is rendered inside the application, independently of
native window backdrop effects.
Kosmo is a code editor built with Merenda and Moe's Vim-style editing engine. It brings together a file browser, split panes, terminal tabs, Markdown previews, and Git diffs. You can use it on its own or explore its source to see how a larger Merenda app fits together.
Use the Files and Find icons at the left of the status bar to switch sidebar views. Click the active icon again to collapse the sidebar and give the editor the full window width; click either icon to reopen it at its previous width.
Press Cmd-F on macOS or Ctrl-F elsewhere to search an editor, Markdown
preview, or Git diff. Use Enter / the arrow buttons to move through matches,
Cmd/Ctrl-G and Shift-Cmd/Ctrl-G for next and previous, and Escape to close.
Editor matches scroll to the center of the pane. Markdown and diff viewers use
case-insensitive literal search; diff search includes collapsed sections and
loads ordinary patches within the viewer's size limits. Open oversized patches
explicitly to include their contents.
Editor search and the Find sidebar open with replacement controls collapsed.
Click the chevron beside the search field to expand or collapse them without
clearing the query or results. On macOS, Option-Cmd-F opens editor replacement
and Option-Shift-Cmd-F opens replacement in files; elsewhere use
Alt-Ctrl-F and Alt-Shift-Ctrl-F. The regular Cmd/Ctrl-F editor shortcut and
Shift-Cmd/Ctrl-F file-search shortcut always return to search only.
Editor replacement offers Replace and Replace All, with one undo step per
operation. In the Find sidebar, run a search, expand replacement, enter text, then
choose Replace for the selected match or Replace All. Both fields treat
text literally by default. Enable .* to use Reni regular expressions in the
query and capture templates in the replacement: $0 is the entire match, $1
and later numbers are captures, ${name} is a named capture, and $$ inserts a
dollar sign. For example, search (?<name>cat|dog) and replace with ${name}!.
When named groups are present, Reni treats unnamed groups as noncapturing.
Matching is line by line, with Unicode-aware offsets; replacement text may
contain newlines. Invalid patterns or capture references show an error, and
invalid replacement templates leave files and buffers untouched. Empty
replacement text deletes matches. File replacement
saves the displayed results, including any search limits, checks that matched lines
still agree with the results, and skips files with unsaved editor changes. Its status
reports replacements and skipped files, then refreshes the search.
Filesystem notifications keep the browser and Quick Open inventory current. On macOS, one FSEvents stream covers a project tree; linked folders and Git metadata outside that tree retain their own streams. If native monitoring cannot cover a path, Kosmo polls periodically and logs the cause and affected paths. Missing directories and exhausted watch capacity are retried automatically.
Open, Open Folder, and Save As share a resizable file browser with Places shortcuts,
Back/Forward/Up navigation, and an editable location field. Enter an absolute path,
a relative folder, or ~/ and press Return to navigate. The file list and Name
column expand with the dialog; Save As keeps the filename below the browser so you
can change folders without losing the name you typed.
You don't need Nim to use a prebuilt Kosmo release. Run the installer from a shell (Git Bash on Windows):
curl -fsSL https://raw.githubusercontent.com/elcritch/merenda/HEAD/install.sh | bashOn macOS, it installs Kosmo.app in ~/Applications and a kosmo command in
~/.local/bin. On Linux, FreeBSD, and Windows, the command goes in
~/.local/bin. Make sure that directory is on your PATH.
Open the current folder or a file:
kosmo .
kosmo README.mdThese commands reuse a running Kosmo instance. Use kosmo --bg ./folder/ to
start a new instance detached from your shell, or kosmo --new ./folder/ to
start a new instance in the foreground. kosmo -v and kosmo --version print
the version and exit. On macOS, you can also open Kosmo.app from Finder.
Add one or more folders to the existing Kosmo window with --add:
kosmo --add ../shared-libraryUse Quick Open to find a file, drag tabs to arrange your panes, or choose File → New Terminal to open a shell. Markdown files open as previews, with a control to switch to the source editor. Merenda Settings places the theme and UI scale in Appearance, fonts in Typography, and scrolling in Behavior.
In Moe's normal mode, :e path opens a Kosmo document tab or selects the file's
existing tab.
:help and :config open reusable tabs; :config keeps Moe's interactive
settings viewer and its selection when you switch tabs, and closes with :q.
:split (:sp) opens the current buffer in a pane below, and :vsplit (:vs)
opens it in a pane to the right. Add a filename to open that file in the new
pane; relative paths use the editor's working directory. :new and :vnew
create empty buffers in those panes. Moe mappings for these commands and
mode_switch config use the same Kosmo tabs and panes.
Settings changes apply to the current Kosmo instance immediately. Choose Save as Default to use the committed theme, fonts, scale, and scrolling choices on the next launch; Reset restores the last saved values. You can also enable Remember changes for future launches to save each committed change automatically.
Terminal tabs sleep on PTY readiness while idle and batch active output into
bounded updates. For native timing measurements with cmatrix or ps, see
terminal latency diagnostics.
Kosmo Settings → Moe Themes includes Catppuccin Latte, Catppuccin Mocha,
Kanagawa Wave, One Dark, and Tokyo Night Moon. These themes are embedded in
the executable and work from any launch directory. Add your own TOML themes
in ~/.config/moe/themes; a user theme with the same name overrides a bundled
theme.
To use a Nim language server, add nimLspCommand to Kosmo's
~/.config/kosmo/config.json and restart Kosmo. The command must be an
absolute executable path followed by any arguments. For example, after building
Nimdex from its checkout:
cd ../nimdex
mkdir -p bin
deps/nim-devel/bin/nim c -d:release -o:bin/nimdex src/nimdex.nimAdd this field to the JSON config, using absolute paths without spaces:
{
"nimLspCommand": "/absolute/path/to/nimdex/bin/nimdex daemon --compiler /absolute/path/to/nimdex/deps/nim-devel/bin/nim"
}Kosmo enables Moe's LSP client when this field is set. In normal mode, press
g then d to go to a definition, or K to show hover information. Remove
the field or set it to an empty string to disable LSP on the next launch.
Nimdex's daemon command communicates over standard input and output and stays
attached to Kosmo; it does not need to detach itself.
Syntax colors arrive progressively as background workers finish small batches. Markdown previews display their content before fenced-code coloring finishes; selection, code-block scroll positions, and text layout survive those color updates.
To add language highlighting, open Kosmo Settings → TextMate Grammars and
search the built-in language grammars in the open-source microsoft/vscode
repository by language name, file extension, or TextMate scope. Select a result
to download, validate, and install its grammar files into Kosmo's user
configuration. This searches VS Code's source repository, not its extension
Marketplace.
You can also send a Git diff straight to Kosmo:
git diff | kosmo --diffRun kosmo --help for command-line options. See the
keyboard shortcut guide for navigation
and Vim bindings, or release and installer details
for supported builds, custom install locations, and the static Linux build.
From your Merenda checkout, install the extra Kosmo dependencies, then build and launch it:
atlas install -tuk --features:kosmo
nim c -o:kosmo src/merenda/kosmo/kosmo.nim
./kosmo .On Windows, run ./kosmo.exe . after compiling.
On macOS, install the current checkout as a complete Kosmo.app with its icon,
bundled notices, debug symbols, and local code signature:
nim install_kosmoThis uses Atlas to resolve dependencies, replaces ~/Applications/Kosmo.app,
and updates the ~/.local/bin/kosmo link. Restart Kosmo if it was already
running. Set KOSMO_INSTALL_DIR or KOSMO_BIN_DIR to choose other locations.
The examples directory has complete apps you can run and change. These are good places to go once you've tried the basics:
- Layouts: stacks and constraints, constraint playground, and the layout guide.
- Tables and trees: table example, filter row (including date range pickers and token fields), outline example, and model controllers.
- App workflows: documents and windows, preferences, and settings and themes.
- Text and drawing: Markdown viewer, canvas, and terminal.
- Building UI from resources: resource guide and example.
- Development checks: reliability and memory profiling.
- Under the hood: NimKit design, Kosmo workspace updates, FigDraw, Siwin, and Sigils.