Bevy UI Builders
Before using bevy-ui-builders
commands.spawn.with_children;
// Plus 30+ more lines for hover system...
After using bevy-ui-builders
use *;
new
.style
.build;
That's it! Hover effects, styling, and interaction handling included.
What's New in v0.2.0
Bevy 0.17 Migration
- Updated to Bevy 0.17 with full compatibility
- Auto-includes
DefaultPickingPluginsfor Interaction components - Breaking changes handled internally
New Builders (3 Added)
- CheckboxBuilder - Interactive checkboxes with toggle states
- Styles: Primary, Success, Danger, Default
- Configurable size and label positioning
- DropdownBuilder - Dropdown select menus
- Click-outside-to-dismiss functionality
- Proper z-index layering (fully opaque overlay)
- NumberInputBuilder - Validated number inputs
- Auto-validates against min/max range
- Shows red border when out of bounds
Universal Validation System
- Composable validation rules work with ANY input (not just forms)
TextInputBuilder.with_validation(Vec<ValidationRule>)method- Visual feedback: red border on error, default border when valid
- ValidationRule types: Required, MinLength, MaxLength, Range, Email, Pattern, Custom
ValidationStateandValidatedECS components
Bug Fixes
- Fixed slider cursor offset bug
- Fixed button hover/press visual feedback
- Fixed scrollbar drag unfocusing when mouse exits window
Complete Builder Count
Now includes 13 builders: Button, Dialog, TextInput, Form, Slider, ProgressBar, Panel, Label, Separator, ScrollView, Checkbox, NumberInput, Dropdown
Quick Start
Add to your Cargo.toml:
[]
= "0.17"
= "0.2"
Add the plugin:
use *;
use UiBuilderPlugin;
In your code, import the prelude for convenient access to all builders:
use *;
Complete Builder Catalog
1. ButtonBuilder - Styled Interactive Buttons
// Simple button
new.build;
// Styled button with all options
new
.style // Primary, Secondary, Success, Danger, Warning, Ghost
.size // Small, Medium, Large, XLarge
.with_marker // Add your own marker component
.margin // Custom margins
.height // Custom height
.enabled // Enable/disable state
.build; // Or use .build_in(parent) alias
// Convenience functions
primary_button.build;
danger_button.build;
ghost_button.build;
2. DialogBuilder - Modal Dialogs with Overlays
// Basic dialog
new
.title
.body
.danger_button
.cancel_button
.dismissible // Can't click outside to close
.z_index // Layer above other UI
.build;
// NEW: Get button entities for custom markers (v0.1.7)
let = new
.title
.confirm_button
.cancel_button
.build_with_buttons;
// Add your own markers to dialog buttons
if let Some = buttons.get
// Helper for single marker
new
.danger_button
.build_and_mark;
// Preset dialogs - static methods
error;
unsaved_changes;
confirm;
3. TextInputBuilder - Native Text Editing with Full Features
// Full-featured text input with native implementation
new
.with_placeholder
.with_filter // Allow letters and numbers
.with_max_length
.with_width // Set width
.with_height // Set height
.with_focus_group // Tab navigation
.with_clear_button // X button to clear
.with_marker
.build;
// Text input with validation (v0.2.0+)
new
.with_placeholder
.with_validation
.build;
// Password input with masking
text_input
.with_placeholder
.password // Masks input with bullets
.build;
// Numeric input
text_input
.numeric_only // Only allows 0-9
.with_value
.build;
Native Features:
- Full cursor rendering with blinking
- Text selection (keyboard Shift+arrows & mouse drag)
- Clipboard operations (Ctrl+C/V/X)
- Undo/Redo support (Ctrl+Z/Shift+Z)
- Proper Tab navigation between inputs
- Auto-scroll when text overflows
- Validation support with visual feedback (v0.2.0+)
4. FormBuilder - Complete Forms with Validation
// Simple login form
new
.title
.text_field
.required
.placeholder
.password_field
.required
.placeholder
.checkbox_field
.submit_text
.cancel_text
.width
.build;
// Complex registration with multiple field types
new
.title
.text_field
.required
.validate
.email_field
.required
.password_field
.required
.validate
.help_text
.dropdown_field
.checkbox_field
.required
.submit_text
.width
.build;
Key API methods:
FormBuilder::new(id: &str)- Constructor takes form ID.text_field(name, label)- Text input field.email_field(name, label)- Email input with validation.password_field(name, label)- Password input (hidden text).checkbox_field(name, label)- Checkbox field.dropdown_field(name, label, options)- Dropdown selection.slider_field(name, label, min, max)- Numeric slider.number_field(name, label, min, max)- Number input with range.required()- Mark previous field as required (chainable).validate(rule)- Add validation rule to previous field (chainable).placeholder(text)- Set placeholder for previous field (chainable).help_text(text)- Add help text below previous field (chainable).submit_text(text)- Set submit button text.cancel_text(text)- Set cancel button text.width(Val)- Set form width.layout(FormLayout)- Set layout (Vertical, Horizontal, Grid)
5. SliderBuilder - Value Sliders with Formatting
// Percentage slider
new
.width
.with_label // Shows "50%"
.with_marker
.build;
// Custom format with new methods
slider
.with_label
.with_format // Alternative to format() method
.with_marker // Add custom marker component
.build_in; // Or use build() alias
6. ProgressBarBuilder - Progress Indicators
// Basic progress bar
new // 75% complete
.style
.with_label // Shows "75%"
.animated // Smooth transitions
.build;
// Custom styled
progress
.fill_color
.track_color
.with_label_text
.build;
7. ScrollViewBuilder - Responsive Scrollable Containers
// Basic scrollable container with viewport-based sizing
new
.width // Set width
.height // Set height
.max_height // 80% of viewport height
.padding_vw // 2% viewport width padding
.padding_vh // 1% viewport height padding
.gap // 2% viewport height gap between children
.margin // Margin around scroll view
.background_color // Background color
.auto_scroll // Auto-scroll to focused elements
.scrollbar_visibility
.build_with_children;
// Horizontal scrolling
scroll_view
.direction
.max_width // 90% viewport width
.build;
// Simple build without children (add content later)
let scroll_entity = new
.width
.height
.build;
Features:
- Viewport-relative sizing (Val::Vh/Vw) for responsive design
- Mouse wheel scrolling support
- Visual scrollbars with auto-hide timeout or always visible
- Auto-scroll to focused text inputs
- Smooth scroll animations
- Draggable scrollbar thumb
- Keyboard scrolling support
Key methods:
.width(Val)- Set container width.height(Val)- Set container height.padding_vh(f32)- Viewport height padding.padding_vw(f32)- Viewport width padding.margin(UiRect)- Set margins.background_color(Color)- Background color.scrollbar_visibility(ScrollbarVisibility)- Always, AutoHide, or Hidden.direction(ScrollDirection)- Vertical (default) or Horizontal.auto_scroll(bool)- Auto-scroll to focused inputs
8. PanelBuilder - Flexible Container Panels
// Card panel with all options
new
.style
.width
.padding
.border_color // Custom border
.flex_grow // Flexbox growth
.flex_shrink // Flexbox shrink
.with_title
.build_with_children;
// Transparent overlay panel
panel
.style
.position_type
.build;
9. LabelBuilder - Consistent Text Labels
// Styled labels
new
.style // Title, Heading, Body, Caption
.text_align
.margin
.build;
// Status labels
label
.style // Error, Success, Warning, Muted
.build;
10. SeparatorBuilder - Visual Dividers
// Horizontal separator
new
.style
.margin
.build;
// Vertical divider
separator_vertical
.style
.length
.build;
11. CheckboxBuilder - Interactive Checkboxes
// Simple checkbox
new
.checked
.with_label
.build;
// Styled checkbox with custom size
new
.checked
.style // Primary, Success, Danger, Default
.with_label
.label_on_right // true = right (default), false = left
.size // Checkbox size in pixels (default: 20.0)
.build;
Features:
- Visual states: unchecked (empty box) and checked (blue fill with white "X")
- Styles: Default, Primary, Success, Danger
- Configurable checkbox size
- Label positioning (left or right)
- Click to toggle state
12. NumberInputBuilder - Validated Number Inputs
// Basic number input
new
.min
.max
.default_value
.build;
// Number input with validation
new
.min
.max
.step
.default_value
.width
.with_placeholder
.build;
Features:
- Automatic range validation (shows red border if out of range)
- Accepts decimal values
- Configurable min/max bounds
- Step size for increment/decrement
- Integrates with universal validation system
- Shows hint text: "Range: min-max"
13. DropdownBuilder - Dropdown Select Menus
// Simple dropdown
new
.build;
// Dropdown with initial selection
new
.placeholder
.selected_index // "Auto" pre-selected
.width
.build;
Features:
- Click-to-open menu overlay
- Click outside to dismiss
- Hover highlights options
- Displays selected value in button
- Fully opaque menu with proper z-index layering
- Only one option highlighted at a time
Cleanup
Generic cleanup system:
// Before: 15 lines of cleanup per UI system
// After: One line, works for ANY component!
app.add_systems;
Note: In Bevy 0.16+, despawn() is automatically recursive - it will despawn all children. The deprecated despawn_recursive() is no longer needed.
Relationship Auto-Cleanup
UI components use Bevy's relationship system with linked_spawn for automatic cleanup:
// When you close a dialog, all related elements (buttons, overlays) are automatically cleaned up
new
.title
.build;
// Relationship components like BelongsToDialog with linked_spawn handle cleanup
// No manual cleanup needed!
Related entities are automatically despawned when the parent is despawned, thanks to the linked_spawn attribute on relationship targets.
Complete Example
Showcasing multiple builders working together:
use *;
use *;
;
This example demonstrates:
- ScrollView with auto-hide scrollbar
- Panel with Card style
- Dropdown for theme selection
- NumberInput with range validation (8-24)
- TextInput with email validation
- Checkboxes for boolean settings
- Slider with percentage formatting
- ProgressBar with label
- Labels and Separators for layout
- Buttons for actions
All 13 builders working together!
Universal Validation System
The crate provides a composable validation system that works across all input types (not just forms).
ValidationRule Types
use *;
// Available validation rules
Required // Field cannot be empty
MinLength // Minimum character length
MaxLength // Maximum character length
Range // Numeric range (for numbers)
Email // Basic email format validation
Pattern // Simple pattern matching
Custom // Custom validator
Adding Validation to Inputs
// Validate any TextInput
new
.with_placeholder
.with_validation
.build;
// NumberInputBuilder has automatic validation
new
.min
.max // Automatically creates ValidationRule::Range { min: 8, max: 24 }
.build;
// Custom validation function
new
.with_validation
.build;
Visual Feedback
When validation fails:
- Input border turns red (
BORDER_ERRORcolor) ValidationStatecomponent stores error messageValidatedcomponent holds validation rules
When validation passes:
- Input border returns to default color
ValidationState.is_valid = true
How It Works
The validation system uses Bevy ECS components:
A system monitors Changed<TextBuffer> and runs all validation rules:
- Checks each rule in order
- Stops at first error
- Updates
ValidationState - Changes border color
Integration with Forms
FormBuilder fields automatically use validation:
new
.text_field
.required // Adds ValidationRule::Required
.validate // Adds custom rule
.email_field
.required // Adds Required + Email rules
.build;
Feature Flags
Control which builders are included:
# Include everything (default)
= "0.2"
# Or pick specific builders
= { = "0.2", = false, = ["button", "dialog"] }
Available features:
button- ButtonBuilderdialog- DialogBuildertext_input- TextInputBuilderform- FormBuilderslider- SliderBuilderprogress- ProgressBarBuilderpanel- PanelBuilderlabel- LabelBuilderseparator- SeparatorBuildercheckbox- CheckboxBuildernumber_input- NumberInputBuilder (depends on text_input)dropdown- DropdownBuildercleanup- Generic cleanup systems
Why Choose bevy-ui-builders?
We Fill The Gap
| Crate | Problem |
|---|---|
bevy_ui_builder |
Too basic, no text inputs or forms |
sickle_ui |
Complex macro system, steep learning curve |
bevy_dioxus |
Requires React/web knowledge |
bevy_egui |
Immediate mode, not native Bevy |
| bevy-ui-builders | Just right! Simple, powerful, pure Bevy |
Unique Features
- Automatic cleanup system - Generic
despawn_ui_entities<T> - Consistent styling - Centralized colors and dimensions
- Rich text inputs - Filtering, validation, focus management
- Type-safe markers - Add your own components to any builder
- Gateway architecture - Clean module boundaries
Bevy Version Support
| bevy-ui-builders | Bevy |
|---|---|
| 0.2 | 0.17 |
License
Dual-licensed under either:
- MIT license (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
at your option.
Contributing
Contributions welcome! Please check CONTRIBUTING.md for development setup, coding standards, and how to submit pull requests.
Credits
Created by Noah Sabaj, the creator of bevy-plugin-builder, and bevy-test-suite.
Bottom Line
// From 45 lines to 3. That's the power of builders.
new
.style
.build;