QrCodeWidget

Display scannable QR codes in your terminal using Unicode block characters (██).

QR codes are rendered as a grid of filled and empty blocks that can be scanned by mobile devices to quickly navigate to URLs, share WiFi credentials, or encode any text data. The primary use case is encoding URLs for easy access from mobile devices.

Basic Usage

Create QR codes using the fluent API:

csharp

dotnet run

The QR code is automatically sized based on the data length. Longer data produces larger QR codes with more modules (the black and white squares).

Terminal Support

QR codes work in all terminals that support Unicode block characters (██). The codes are scannable with standard QR code reader apps on smartphones.

Quiet Zone

The quiet zone is the white border around the QR code. By default, QrCodeWidget uses a quiet zone of 1 module width. You can customize this:

csharp

// Default quiet zone (1 module)
v.QrCode("https://hex1b.dev")

// No quiet zone
v.QrCode("https://hex1b.dev").WithQuietZone(0)

// Larger quiet zone (4 modules)
v.QrCode("https://hex1b.dev").WithQuietZone(4)

QR Code Standards

QR code specifications recommend a quiet zone of at least 4 modules for optimal scanning reliability. However, in controlled terminal environments where the QR code is displayed on a clean background, smaller quiet zones (1-2 modules) work well and save space.

Interactive Example

Here's a complete example with URL selection and quiet zone controls:

csharp

dotnet run

This example demonstrates:

• Dynamic QR code updates when the URL changes
• Picker widget for URL selection
• Buttons to adjust the quiet zone
• Real-time re-rendering as state changes

Data Encoding

QrCodeWidget uses error correction level Q (Quartile), which provides 25% data recovery capability. This is a good balance between:

• Error resilience: Can recover from moderate damage or distortion
• Data capacity: Supports reasonable URL lengths without excessive QR code size

Supported Data

While the primary use case is URLs, QrCodeWidget can encode any text data:

// URLs
v.QrCode("https://github.com/mitchdenny/hex1b")

// Plain text
v.QrCode("Hello, World!")

// WiFi credentials (using standard format)
v.QrCode("WIFI:T:WPA;S:MyNetwork;P:MyPassword;;")

// Contact information
v.QrCode("BEGIN:VCARD\\nFN:John Doe\\nTEL:+1234567890\\nEND:VCARD")

Data Length Limits

QR codes have size limits based on error correction level and version. If the data is too long to encode, QrCodeWidget gracefully handles the error by displaying an empty area. Keep URLs under 200 characters for best results.

Rendering Details

QrCodeWidget renders QR codes using double-width Unicode block characters:

• Filled modules: ██ (full block character, doubled for square appearance)
• Empty modules: (two spaces)

This double-width approach ensures QR codes appear roughly square in most terminal fonts, which typically have character cells about twice as tall as they are wide.

Size Calculation

The widget automatically measures itself based on:

1. The QR code matrix size (determined by data length and error correction)
2. The quiet zone on all four sides

For example, a 25×25 module QR code with a quiet zone of 1 becomes 27×27 characters in the terminal.

Theming

QrCodeWidget respects theme colors from parent widgets:

using Hex1b;
using Hex1b.Theming;

var theme = new Hex1bTheme("Custom")
    .Set(ThemeElement.ForegroundColor, Hex1bColor.Green)
    .Set(ThemeElement.BackgroundColor, Hex1bColor.Black);

await using var terminal = Hex1bTerminal.CreateBuilder()
    .WithHex1bApp((app, options) =>
    {
        options.Theme = theme;
        return ctx => ctx.ThemePanel(tp => [
            tp.Text("Green QR Code:"),
            tp.QrCode("https://hex1b.dev")
        ])
        .WithForegroundColor(Hex1bColor.Green);
    })
    .Build();

await terminal.RunAsync();

The block characters inherit the foreground color from the theme, allowing you to create colored QR codes that still scan correctly.

Use Cases

Application URLs

Share links to documentation, repositories, or web applications:

v.VStack(stack => [
    stack.Text("Visit our documentation:"),
    stack.QrCode("https://hex1b.dev/guide/getting-started")
])

Configuration Sharing

Encode configuration data for easy transfer to mobile devices:

var config = $"CONFIG:server={server};port={port};key={apiKey}";
v.QrCode(config)

Status Dashboard

Display QR codes that link to detailed status pages or logs:

v.HStack(row => [
    row.VStack(info => [
        info.Text($"Build: {buildNumber}"),
        info.Text($"Status: {status}")
    ]),
    row.QrCode($"https://build-server.com/build/{buildNumber}")
])

Related Widgets

• TextWidget - For displaying text content
• HyperlinkWidget - For clickable terminal hyperlinks
• PickerWidget - For selection lists (pairs well with QR codes)