<p align="center">
  <img src="https://github.com/rio-labs/rio/blob/main/assets/readme_logo.svg?raw=true" alt="Rio Logo" style="width: 100%; height: 9rem"/>
</p>

<p align="center">
  <strong>Rio</strong> is an easy to use framework for creating websites and apps and is based <strong>entirely on Python</strong>. 🐍
  <br>
  You <strong>won't need a single line of HTML, CSS, or
  JavaScript</strong> to create beautiful, modern apps.<br><br>
  <a href="https://rio.dev/get-started?s=pl1">Tutorial</a> - <a href="https://rio.dev/examples?s=g8r">Examples</a> - <a href="https://discord.gg/7ejXaPwhyH">Discord</a> - <a href="https://rio.dev/docs?s=o1z">Docs</a> - <a href="https://github.com/rio-labs/rio">Source Code</a><br><br>
  Rio brings React-style components to Python. Pull from a wealth of built-in
  components and combine them to create your own custom components. Then combine
  those into entire apps. Best of all, Rio apps can run both locally on your
  machine and on the web.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Rio-outline.svg?color=%2311e8e3e&link=https%3A%2F%2Frio.dev&style=flat-square&logo=data:image/svg%2bxml;base64, " alt="Rio"/>
  <img src="https://img.shields.io/pypi/v/rio-ui?color=%2311e8e3e&style=flat-square" alt="Version"/>
  <!--
  <img src="https://img.shields.io/discord/1213589765484576818?color=%2311e8e3e&label=discord&style=flat-square" alt="Discord"/>
  -->
  <img src="https://img.shields.io/pypi/pyversions/rio-ui?style=flat-square" alt="Python Version"/>
  <img src="https://img.shields.io/pypi/l/rio-ui?color=%2311e8e3e&style=flat-square" alt="License"/>
  <img src="https://img.shields.io/github/stars/rio-labs/rio?style=flat-square" alt="GitHub Stars"/>
  <img src="https://img.shields.io/pypi/dm/rio-ui?color=%2311e8e3e&style=flat-square" alt="Downloads"/>
</p>

![Image Generation Example](https://github.com/rio-labs/rio/assets/41641225/44279406-0c2d-47e2-98b5-4582722054b2)

## Features 🧩

- Modern, **declarative UI** framework
- **100% Python** - Zero HTML, CSS, or JavaScript required
- Over **50 Built-in components** for common UI elements, such as `rio.Switch`, `rio.Button`, and `rio.Text`, and many more
- Integrates with **modern Python tooling**: Thanks to being **entirely Type Safe** editors can give you instant suggestions and highlight problems right away
- Apps can run **both locally and on the web**
- **Dev tools** included
- **Open Source & Free forever**

## Example ⌨️

```python
# Define a component that counts button clicks
class ButtonClicker(rio.Component):
    # Define the attributes of the component. Rio will watch these
    # for changes and automatically update the GUI.
    clicks: int = 0

    # Define a method that increments the click count. We'll later
    # make a button that calls this method whenever it is pressed.
    def _on_press(self) -> None:
        self.clicks += 1

    # Define the `build` method. This method essentially tells rio
    # what a ButtonClicker component looks like. Whenever the state
    # of the ButtonClicker component changes, rio will call its
    # `build` method and update the GUI according to the output.
    def build(self) -> rio.Component:
        return rio.Column(
            rio.Button('Click me', on_press=self._on_press),
            rio.Text(f'You clicked the button {self.clicks} time(s)'),
        )

# Create an App and tell it to display a ButtonClicker when it starts
app = rio.App(build=ButtonClicker)
app.run_in_browser()  # Or `app.run_in_window()` to run as local app!
```

## Installation 🛠️

Rio is available on PyPI, so you can install it using pip:

```bash
pip install rio-ui
```

## Getting Started 🎓

Rio comes with a very helpful command line utility to help you out. Create a new project in one short command:

```bash
rio new
```

You can choose from a variety of built-in templates to get you started. Here's a complete example to create a project based on the tic-tac-toe template:

```bash
rio new my-project --type website --template "Tic-Tac-Toe"
cd my-project
rio run
```

You'll have your first app up and running in seconds!

## Status: Beta 🚧

Rio is rapidly approaching its first stable release. Version 0.10 incoroparates
all _planned_ breaking changes. Minor changes may still occur, but we are
actively trying to avoid them.

If you encounter any issues or would like to provide feedback, please let us
know on [our Discord server](https://discord.gg/7ejXaPwhyH).

1.0 is expected later this year.

## Contributing 🤝

**Every project thrives with a helping hand**, and that's especially true for
Rio. **There are lots of ways to jump in**, like adding new features, fixing
bugs, or just sharing your ideas. Check out our [Contributing
Guide](https://github.com/rio-labs/rio/blob/main/CONTRIBUTING.md) when submitting
a Pull Request to the project. Rio keeps getting better with new features
rolling out every week. **Star ⭐ and 👀 watch this repo to stay in the loop!**

Unless you explicitly state otherwise, any contribution submitted for inclusion
in Rio shall be licensed under the terms of the Apache-2.0 license, without any
additional terms or conditions.

## Community Support 🫶

**Join the Rio adventure and be part of an awesome fellowship! Here is how to get in touch:**

- [Discord](https://discord.gg/7ejXaPwhyH) (Level up your Rio skills! **Join our Discord server** to chat with other developers and discuss how to contribute.)
- [GitHub](https://github.com/rio-labs/rio) (**Spot a bug?** Issues are the perfect place to let us know. Feeling super-helpful? Try fixing an existing issue and submit a PR!)
- [Community Forum](https://github.com/rio-labs/rio/discussions) (**Join our community forum on Github** for asking questions and discussions)
- [Feature Requests](https://github.com/rio-labs/rio/discussions/categories/feature-requests) (Cleanest way to **request a feature** on GitHub)

For general help using Rio, please refer to the [official Rio documentation](https://rio.dev/docs?s=t9s).
