Welcome to the Rio Docs

Rio is your friendly companion for web and app development, especially if you're not a web design expert but know some Python. This page is a perfect starting point to explore Rio and learn how to build your very own web apps. Whether you're a beginner or have specific questions, Rio is here to simplify things for you. To get started, head over to the Get Started Guide and begin your journey with Rio!

Our Motivation for Rio

We have created Rio to address the challenges Python developers face when building modern web apps. Python is extremely simple and concise, making it one of the most popular programming languages in the world. Existing frameworks often require additional skills in HTML, CSS, or JavaScript, adding complexity and creating barriers for developers who prefer Python's simplicity. Recognizing Python's potential for streamlined and compact development, we envisioned a framework that allows users to focus entirely on Python without sacrificing functionality or flexibility.

Rio eliminates the traditional divide between frontend and backend. Its automated communication simplifies development, removing the need for defining endpoints or sending requests manually. Inspired by the best aspects of frameworks like Flutter and React, Rio introduces a declarative interface, reusable components, and dynamic attribute binding to Python. These features enable developers to create powerful and maintainable applications with minimal effort.

Many projects rely on popular libraries like React internally, but the core benefits and elegance of these libraries are often diluted in the process. Take React, for example—its defining feature is that the "app is code," where components are dynamically built within a render method that automatically re-triggers upon state changes. However, this fundamental principle is lost in libraries that simply wrap React. It contradicts the very premise of React and the reasons for its widespread popularity among developers.

Rio reduces repetitive tasks and enhances productivity with built-in support for modern developer experience, such as hot reloading, static typing, targeted error messages in both the console and GUI. Its clean structure and unlimited GUI designs with fully customizable and reusable components make it versatile enough for hobby projects, proof of concepts, and production-grade applications alike.

How Rio Works

The user code is written entirely in Python and is responsible for defining the UI components of the app or website. From this point, Rio takes over: the components are automatically converted into HTML, CSS, and JavaScript, which are sent to the user's browser.

A WebSocket connection keeps the server and client in sync. When a user interacts with the website, a message is automatically sent to the server, and UI updates are synchronized with the client. This process requires no intervention from the developer—there's no need to manually define endpoints or send HTTPS requests.

On the client side, Rio's layout system manages the positioning of components on the screen and dynamically adjusts the website's DOM based on the server's instructions.

Rio components are the building blocks of your web app. They are the visual elements that the user interacts with. You can use them to create buttons, text inputs, images, and more. Each component has its own set of properties that you can customize to fit your needs.

To learn more about Rios components, head over to Components API Guide.

A Fresh Layouting System

When it comes to building modern apps, components are just the beginning, it's the layouting that pulls them together into a cohesive, user-friendly interface. Designing a layout system isn't a one-size-fits-all task; different frameworks bring unique strengths, with CSS often at the center of debate. As we designed Rio's layout system, we aimed for something Pythonic, simple, flexible, and efficient—a system that keeps developers focused on their app's function, not the complexities of positioning. Here are some core principles behind Rio's two-step approach to layouting, where each component starts by defining its own natural size before the available space is thoughtfully distributed:

• Pythonic: Rio embraces Python's simplicity. No numbers encoded as strings or complex unit declarations. For example, width=10 is preferred over width="10px". This isn't just cleaner, but also aids type checking tools and allows for easy mathematical operations.

• Simple: The system should be intuitive, even for developers without a deep background in UI design. Rather than a tangled set of rules and exceptions, it should be governed by a handful of principles that are applied consistently.

• Flexible: From basic layouts to complex, nested structures, the system needs to handle them all. Templates and restrictive built-in patterns won't cut it.

• Efficient: Especially when targeting the web, performance is key. A good layouting system should be automatically convertible to CSS, maybe with some JavaScript sprinkled in occasionally for dynamic calculations.

Take a look at our playground, where you can try out our layout concept firsthand with just a click and receive real-time feedback. Layouting Quickstart

Cookbook

The Cookbook section is your essential resource for exploring the creative potential of the Rio framework. The Cookbook offers a rich collection of hands-on examples and step-by-step guides that demonstrate how to build on Rio's +50 Material Design 3 core components, showing you how they seamlessly integrate to create a fluid and engaging UI. By working through detailed recipes for building custom tables that feature advanced filtering and multi-selection, crafting intuitive custom dropdowns for flexible option selection, and designing innovative custom Navbars or Sidebars that enhance navigation, you'll quickly see how these components work together to form robust, interactive modern interfaces.

These examples aren't just meant to be followed, they are designed to inspire you to go further, empowering you to expand on the provided concepts using your own creativity. From here, the only limit is your imagination, allowing you to customize and optimize every detail for your own projects. Cookbook