socktop-webterm/TRANSPARENCY_GUIDE.md

Terminal Transparency Guide

Overview

The terminal now supports transparency, allowing you to see your beautiful background image through the terminal! This uses xterm.js's allowTransparency option combined with CSS backdrop-filter for a modern, polished look.

How It Works

The transparency is achieved through three components:

1. xterm.js allowTransparency option - Enables transparency support
2. Theme background color with alpha - Sets the opacity level
3. CSS backdrop-filter - Adds optional blur effect

Current Setup

Terminal Configuration (JavaScript)

var term = new Terminal({
    allowTransparency: true,
    theme: {
        background: "rgba(0, 0, 0, 0.7)", // 70% opaque black
    },
});

Container Styling (CSS)

#terminal {
    background: transparent;
    backdrop-filter: blur(10px); /* Blur effect */
    border: 1px solid rgba(255, 255, 255, 0.2);
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
}

Customizing Transparency Level

Option 1: Adjust Terminal Background Opacity

In templates/term.html, find the Terminal constructor and modify the alpha value:

var term = new Terminal({
    allowTransparency: true,
    theme: {
        background: "rgba(0, 0, 0, 0.7)", // Change the last number (0.7)
    },
});

Opacity Values:

• 0.0 = Fully transparent (you'll see everything through)
• 0.3 = Very transparent (light tint)
• 0.5 = Half transparent (moderate tint)
• 0.7 = Somewhat opaque (recommended, current value)
• 0.9 = Nearly opaque (just a hint of transparency)
• 1.0 = Fully opaque (no transparency)

Option 2: Change Background Color

You can use any color, not just black:

// Dark blue with transparency
background: "rgba(0, 20, 40, 0.7)"

// Dark purple with transparency
background: "rgba(30, 20, 50, 0.7)"

// Dark green with transparency (Matrix style!)
background: "rgba(0, 20, 0, 0.8)"

// Use your theme colors
background: "rgba(48, 52, 70, 0.7)" // Catppuccin Frappe base

Option 3: Adjust Blur Amount

In the CSS, modify the backdrop-filter value:

/* No blur - sharp background */
backdrop-filter: none;

/* Light blur */
backdrop-filter: blur(5px);

/* Medium blur (current) */
backdrop-filter: blur(10px);

/* Heavy blur */
backdrop-filter: blur(20px);

/* Blur + brightness adjustment */
backdrop-filter: blur(10px) brightness(0.8);

Option 4: Remove Blur Entirely

If you prefer sharp background with no blur:

#terminal {
    background: transparent;
    backdrop-filter: none; /* Remove this line or set to none */
}

Preset Styles

Glassy Effect (Recommended)

// In Terminal constructor
theme: {
    background: "rgba(0, 0, 0, 0.6)",
}

/* In CSS */
#terminal {
    backdrop-filter: blur(15px);
    border: 1px solid rgba(255, 255, 255, 0.2);
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
}

Minimal Transparency

theme: {
    background: "rgba(0, 0, 0, 0.85)",
}

#terminal {
    backdrop-filter: blur(5px);
}

Maximum Transparency (Bold!)

theme: {
    background: "rgba(0, 0, 0, 0.4)",
}

#terminal {
    backdrop-filter: blur(20px) brightness(0.8);
}

Frosted Glass Effect

theme: {
    background: "rgba(255, 255, 255, 0.1)", // Light background
    foreground: "#000000", // Dark text
}

#terminal {
    backdrop-filter: blur(30px) saturate(180%);
    border: 1px solid rgba(255, 255, 255, 0.3);
}

Acrylic Effect (Windows 11 style)

theme: {
    background: "rgba(32, 32, 32, 0.7)",
}

#terminal {
    backdrop-filter: blur(40px) saturate(125%) brightness(0.9);
    border: 1px solid rgba(255, 255, 255, 0.15);
    box-shadow: 
        0 8px 32px rgba(0, 0, 0, 0.3),
        inset 0 1px 0 rgba(255, 255, 255, 0.1);
}

Full Theme Customization

You can customize more than just the background:

var term = new Terminal({
    allowTransparency: true,
    theme: {
        background: "rgba(0, 0, 0, 0.7)",
        foreground: "#d4d4d4",          // Text color
        cursor: "#ffffff",              // Cursor color
        cursorAccent: "#000000",        // Cursor text color
        selection: "rgba(255, 255, 255, 0.3)", // Selection highlight
        
        // ANSI Colors
        black: "#000000",
        red: "#e74856",
        green: "#16c60c",
        yellow: "#f9f1a5",
        blue: "#3b78ff",
        magenta: "#b4009e",
        cyan: "#61d6d6",
        white: "#cccccc",
        
        // Bright ANSI Colors
        brightBlack: "#767676",
        brightRed: "#e74856",
        brightGreen: "#16c60c",
        brightYellow: "#f9f1a5",
        brightBlue: "#3b78ff",
        brightMagenta: "#b4009e",
        brightCyan: "#61d6d6",
        brightWhite: "#f2f2f2",
    },
});

Browser Compatibility

backdrop-filter is supported in:

• ✅ Chrome/Edge 76+
• ✅ Safari 9+
• ✅ Firefox 103+
• ✅ Opera 63+

For older browsers, the terminal will still work but without the blur effect.

Performance Considerations

Blur effects can impact performance, especially on:

• Lower-end devices
• Large terminal windows
• Systems without GPU acceleration

If you experience lag:

1. Reduce blur amount: blur(5px) instead of blur(20px)
2. Remove blur entirely: backdrop-filter: none;
3. Increase opacity: Use 0.8 or 0.9 instead of 0.5

Tips for Best Results

1. Match your background: Use a background color that complements your page background
2. Readability first: Ensure text is still readable - don't go too transparent
3. Test in different lighting: What looks good in dark mode might not work in light mode
4. Consider your content: Busy backgrounds may need more opacity or blur

Examples with Different Backgrounds

Dark Background Image

theme: { background: "rgba(0, 0, 0, 0.6)" } // More transparent OK

Light Background Image

theme: { background: "rgba(0, 0, 0, 0.8)" } // Need more opacity for contrast

Busy/Complex Background

theme: { background: "rgba(0, 0, 0, 0.75)" } // More opacity
// Plus heavy blur
backdrop-filter: blur(20px);

Simple/Minimal Background

theme: { background: "rgba(0, 0, 0, 0.5)" } // Can go more transparent
// Light or no blur
backdrop-filter: blur(5px);

Troubleshooting

Background not showing through

• Check allowTransparency: true is set
• Verify background has alpha channel: rgba(r, g, b, alpha) not rgb(r, g, b)
• Make sure container background is transparent not a solid color

Text hard to read

• Increase opacity: Change 0.5 to 0.7 or 0.8
• Add more blur: blur(15px) or blur(20px)
• Darken background: Use rgba(0, 0, 0, 0.8) instead of lighter values

Blur not working

• Check browser compatibility
• Verify CSS syntax: backdrop-filter: blur(10px);
• Try without vendor prefixes first

Performance issues

• Reduce blur amount
• Increase opacity
• Use simpler background image
• Disable backdrop-filter

Quick Reference

/* Transparency Level */
rgba(0, 0, 0, 0.5)  ← Change this number (0.0 to 1.0)

/* Blur Amount */
backdrop-filter: blur(10px);  ← Change this number

/* Remove blur entirely */
backdrop-filter: none;

---

Enjoy your transparent terminal! 🎨✨

Experiment with different values to find what looks best with your background image and personal style.