Raxol (Raxol v0.3.0)
View SourceRaxol is a feature-rich terminal UI framework for Elixir.
It provides a comprehensive set of components and tools for building beautiful, accessible, and responsive terminal applications.
Features
Modern Component Library: A rich set of pre-built UI components like buttons, text inputs, tables, modals, and more.
Accessibility Support: Built-in features for screen readers, high contrast mode, and keyboard navigation.
Theming System: Customize the look and feel of your application with consistent theming.
Responsive Layouts: Create layouts that adapt to different terminal sizes.
The Elm Architecture: Follows TEA (The Elm Architecture) for predictable state management.
Event Handling: Comprehensive event system for keyboard, mouse, and terminal events.
Getting Started
To create a new Raxol application, you need to define three core functions:
init/1
: Initializes your application stateupdate/2
: Updates the state based on eventsrender/1
: Renders the UI based on the current state
Here's a simple counter example:
```text
defmodule Counter do
@behaviour Raxol.Core.Runtime.Application
require Raxol.Core.Renderer.View
alias Raxol.Core.Runtime.Events.Event
def init(_opts) do
{%{count: 0}, []}
end
def update(%{count: count} = model, %Event{type: :command, data: :increment}) do
{%{model | count: count + 1}, []}
end
def update(%{count: count} = model, %Event{type: :command, data: :decrement}) do
{%{model | count: count - 1}, []}
end
def update(model, _event_or_msg), do: {model, []}
def view(model) do
Raxol.Core.Renderer.View.column [padding: 1] do
[
Raxol.Core.Renderer.View.text("Count: #{model.count}"),
Raxol.Core.Renderer.View.row [gap: 1] do
[
Raxol.Core.Renderer.View.button "-", on_click: {:command, :decrement},
Raxol.Core.Renderer.View.button "+", on_click: {:command, :increment}
]
end
]
end
end
end
# Start the application
Raxol.run(Counter)
```
Architecture
Raxol is built on the Elm Architecture:
- Model: Your application state
- Update: Logic to update the state based on messages
- View: Pure functions to render UI based on the current state
Messages can be generated by user interactions (like button clicks) or system events (like terminal resize).
Components
Raxol provides a rich set of built-in components in the Raxol.Components module. Common components include:
- Buttons
- Text inputs
- Tables
- Progress indicators
- Modals
- Dropdown menus
- Tab bars
Each component follows consistent patterns for styling and behavior.
Summary
Functions
Gets the current accessibility settings.
Gets the current default theme.
Runs a Raxol application.
Enables or disables accessibility features.
Sets the default theme for Raxol applications.
Gracefully stops a running Raxol application.
Returns information about the terminal environment.
Returns the current version of Raxol.
Functions
Gets the current accessibility settings.
Returns
A map of current accessibility settings.
Example
settings = Raxol.accessibility_settings()
if settings.high_contrast do
# Do something for high contrast mode
end
Gets the current default theme.
Returns
The current theme map.
Example
theme = Raxol.current_theme()
Runs a Raxol application.
This function starts the Raxol runtime with the provided application module
and options. The application module must implement the Raxol.Core.Runtime.Application
behaviour.
Parameters
app
- Module implementing theRaxol.Core.Runtime.Application
behaviouropts
- Additional options for the runtime
Options
:quit_keys
- List of keys that will quit the application (default:[{:ctrl, ?c}]
):fps
- Target frames per second (default:60
):title
- Terminal window title (default:"Raxol Application"
):font
- Terminal font (if supported):font_size
- Terminal font size (if supported):accessibility
- Accessibility options:screen_reader
- Enable screen reader support (default:true
):high_contrast
- Enable high contrast mode (default:false
):large_text
- Enable large text mode (default:false
)
Returns
The return value of the application when it exits.
Example
Raxol.run(MyApp, %{initial: "state"}, title: "My Application", fps: 30)
Enables or disables accessibility features.
Parameters
opts
- Map of accessibility features to enable/disable
Options
:screen_reader
- Enable screen reader support:high_contrast
- Enable high contrast mode:large_text
- Enable large text mode:reduced_motion
- Reduce or eliminate animations
Example
Raxol.set_accessibility(screen_reader: true, high_contrast: true)
Sets the default theme for Raxol applications.
This function sets the default theme that will be used by Raxol components.
Parameters
theme
- A theme created withRaxol.UI.Theming.Theme.new/1
or one of the built-in themes
Example
# Use a built-in theme
Raxol.set_theme(Raxol.UI.Theming.Theme.dark())
# Create and use a custom theme
custom_theme = Raxol.UI.Theming.Theme.new(name: "Custom", colors: %{primary: :green})
Raxol.set_theme(custom_theme)
Gracefully stops a running Raxol application.
This function can be called from within your application to exit gracefully.
Parameters
return_value
- Value to return from theRaxol.run/3
function
Example
def update(model, :exit) do
Raxol.stop(:normal)
model
end
Returns information about the terminal environment.
This includes terminal size, color support, and other capabilities.
Returns
A map with terminal information.
Example
Raxol.terminal_info()
# => %{
# name: "iTerm2",
# version: "3.5.0",
# features: [:true_color, :unicode, :mouse, :clipboard],
# ...
# }
Returns the current version of Raxol.
Returns
A string representing the current version.
Example
Raxol.version()
# => "1.0.0"