Submitting to the Showcase

The Ratatui showcase is curated. It is not meant to be a complete directory of every Ratatui app or widget. We are intentionally selecting a set of entries that work well together on the site and help show what Ratatui can do. The goal is to highlight entries that make someone stop, immediately understand what is interesting, and want to click through to learn more.

That means there is some judgment involved in showcase reviews. Sometimes that means rejecting a submission, or suggesting changes that are not strictly about the app or widget library itself, but about how the entry works as part of the curated set. That can include things like framing, capture, pacing, contrast, layout, or how much of the UI is shown. We still want the reasoning to be clear and consistent, so this page explains what we tend to optimize for and why.

This guidance consolidates ideas from previous discussions in #986, #905, and #1032, along with feedback repeated across showcase submissions and review threads.

If your project is not a good fit for the showcase today, that does not mean it is not useful or well made. We encourage you to share it on Awesome Ratatui, the forum, or Discord. In some cases the reason may be presentation, and in others it may be overlap with existing showcase entries or the limited space on a curated page.

What the showcase is for

The showcase is optimized for:

first impressions
visual clarity at a glance
entries that still read well when resized on the website, in a GitHub PR, or on a phone
giving people ideas for making cool TUIs
driving traffic to third-party apps and widgets in the ecosystem
showing a range of interesting approaches to building with Ratatui
a small number of strong examples rather than a complete catalog

A useful test is whether someone can see the image or GIF, understand what is compelling within a second or two, and feel like they want to try the project.

Principles behind the feedback

Most review comments are trying to improve one of these principles:

Legibility. Text, borders, labels, and structure should still be readable when the media is scaled down.
Contrast. Dim text, low-contrast separators, and thin visual details often disappear on the website.
Visual hierarchy. The important part of the UI should stand out immediately.
Signal over coverage. A single strong view is usually better than showing every possible mode, configuration, or feature.
Calm motion. Animation should help people understand the UI, not make it harder to parse.
Intentional composition. Empty space, crowded layouts, and too many competing colors make entries feel less polished.

These are the reasons behind feedback such as “use a smaller width”, “increase dwell time”, or “simplify the layout”. Those are not arbitrary rules. They are proxies for clarity.

The bar for apps

The apps page is intentionally selective. In practice, new submissions should look better than a large share of the apps already on the page, and the safest submissions usually land closer to the top tier than the middle.

Strong app submissions usually have most of these qualities:

The UI looks polished rather than prototype-like.
The purpose of the app is obvious from a single screenshot or short GIF.
The visual design feels intentional, with clear hierarchy and spacing.
The app uses color and contrast well instead of relying on a flat or muddy palette.
The recording focuses on the app, not the shell command used to launch it.
The entry feels stable and production-ready rather than experimental or broken.

Common reasons for pushback:

The UI looks too plain, cluttered, or unfinished
There is too much whitespace or too many boxes competing for attention
The media is visually busy and does not make the app’s purpose obvious
The color choices reduce readability or fail to create hierarchy
The app may be useful, but it is not a strong fit for the curated showcase

For built-in widgets and third-party widget libraries, the goal is slightly different. We are not trying to show every option the widget supports. We are trying to show why someone would want to use it.

Strong widget submissions usually:

choose one or two compelling states instead of every permutation
crop or zoom the scene so the widget occupies more of the frame
use text sizes that match the rest of the showcase
avoid dense grids of tiny examples
keep labels readable without pausing frame-by-frame

If a widget is highly configurable, the right place to show every variation is usually your own repository or docs. The showcase should usually present a single strong hero view that makes the widget’s value obvious.

Media guidelines

These are the practical rules we keep repeating because they work well across the website and GitHub:

Prefer a width in the 800-1200px range. 1200 is a good default ceiling.
Prefer the default VHS font size or something visually similar.
Use a dark theme unless you have a compelling reason not to.
Hide the shell command and unrelated setup noise.
Keep the subject large in frame. Remove wasted margins and padding where possible.
Give viewers enough dwell time to read the screen before changing state.
Use GIFs only when motion helps explain the UI. A screenshot is often better.
Avoid fast cuts, simultaneous changes everywhere, or long sequences of tiny states.
Check the result on a phone-sized viewport before submitting.

For storage:

Prefer GitHub attachments, vhs publish, your own hosting, or Git LFS.
Avoid committing large binary screenshots directly into normal Git history when possible.

Where to submit instead

Not every project belongs on the curated showcase, but there are still good places to share it:

Those are great places for early projects, niche tools, libraries with less visual focus, or apps that are useful but not yet showcase-ready.

Before opening a PR or issue

If you want feedback on a possible showcase entry, open a showcase submission issue first:

Open a showcase submission issue

Please review your submission against this checklist:

Does the media make the core idea obvious immediately?
Is the text still readable when resized?
Does the UI have clear hierarchy and good contrast?
Have you removed extra modes, whitespace, and low-value variation?
Does the animation linger long enough to understand each important state?
Would this stand out positively next to the current showcase entries?
Is the project already documented and shared in a place like Awesome Ratatui?

If the answer to several of those is “not yet”, you will probably have a better experience by iterating on the presentation first.