# How to Customize Column Separator Characters in Outfancy Tables

> Customize column separator characters in Outfancy with the separator argument in the Table.render method. Enhance your table's appearance easily.

- Repository: [Carlos A. Planchón/outfancy](https://github.com/carlosplanchon/outfancy)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Outfancy allows you to customize the string that appears between columns by passing a `separator` argument to the `Table.render` method in [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py).**

The outfancy library provides flexible table formatting for terminal output. When rendering tables, you can control the visual delimiter between columns using the built-in `separator` parameter. This guide explains how to customize the separator characters in outfancy tables using the `Table.render` method and its validation logic.

## Understanding the Separator Parameter

The primary mechanism for customizing column separators is the `separator` parameter in the `Table.render` method.

### The Render Method Signature

In [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py), the `render` method accepts a `separator` argument with the signature `separator: str | None = None` 【4†L52-L55】. When provided, this string is inserted between each column in the output row.

### Default Fallback Behavior

If you omit the `separator` argument or pass `None`, the method defaults to a single blank space (`' '`). This default is also enforced by the `Table.check_separator` method when validation fails 【5†L31-L35】.

## Validating Custom Separator Characters

Outfancy validates custom separators to ensure they render correctly within terminal boundaries.

The `Table.check_separator` method in [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py) performs two critical checks 【5†L31-L44】:

- The separator must be a string type.
- The **printed length** must not exceed the terminal width (`screen_x`).

If either check fails, the library silently falls back to a single space and logs an error. The printed length calculation uses `widgets.printed_length` to properly handle ANSI escape codes, ensuring colored separators are measured correctly.

## Code Examples for Custom Separators

Here are practical implementations ranging from simple pipes to advanced styling.

### Basic Pipe Separator

Use a simple pipe character to create a CSV-like visual output:

```python
from outfancy.table import Table

tbl = Table()
data = [(1, "Alice", 23), (2, "Bob", 30)]

# Use a simple pipe character

print(tbl.render(data, separator="|"))

```

### Visual Unicode Separators

Multi-character separators with box-drawing characters provide clearer visual separation:

```python

# Multi-character separator with box-drawing characters

print(tbl.render(data, separator=" │ "))

```

### ANSI Colored Separators

Embed color codes directly in the separator string. The `widgets.printed_length` function in [`outfancy/widgets.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/widgets.py) strips these codes before validation:

```python

# Green star separator using ANSI escape codes

print(tbl.render(data, separator="\x1b[32m★\x1b[0m"))

```

### Handling Length Validation

If the separator exceeds the terminal width, `check_separator` automatically falls back to a single space:

```python

# This 100-character separator exceeds typical terminal widths

long_sep = "—" * 100

# Automatically falls back to single space " " due to check_separator logic

print(tbl.render(data, separator=long_sep))

```

As implemented in [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py), the `check_separator` method replaces overly long separators with a single space to prevent display corruption 【5†L31-L44】.

### Reusable Custom Separator via Subclassing

For projects requiring consistent styling, subclass `Table` and store the separator as an instance attribute:

```python
class FancyTable(Table):
    def __init__(self, sep=" | "):
        super().__init__()
        self._sep = sep
    
    def render(self, *args, **kwargs):
        # Inject preferred separator unless caller overrides it

        kwargs.setdefault("separator", self._sep)
        return super().render(*args, **kwargs)

# Create instance with custom default separator

fancy = FancyTable(sep=" ▸ ")
print(fancy.render(data))

```

## Summary

- Pass a string to the `separator` argument of `Table.render` in [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py) to customize column delimiters.
- The default separator is a single space (`' '`) when the argument is omitted or invalid.
- `Table.check_separator` validates that the separator is a string and fits within the terminal width (`screen_x`).
- Invalid or overly long separators silently fall back to a single space with an error logged.
- For reusable styling, subclass `Table` and override `render` to inject your preferred separator automatically.

## Frequently Asked Questions

### What is the default column separator in outfancy?

According to the source code in [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py), the default separator is a single blank space (`' '`). This value is used when you omit the `separator` argument or when `Table.check_separator` determines the provided value is invalid 【5†L31-L35】.

### Can I use ANSI color codes or Unicode symbols as column separators?

Yes. The library supports ANSI escape codes and Unicode characters in the `separator` string. The `widgets.printed_length` helper strips color codes before measuring the separator's length against the terminal width, allowing colored separators like `"\x1b[32m★\x1b[0m"` to render correctly without triggering validation failures.

### What happens if my custom separator is longer than the terminal width?

If the separator's printed length exceeds the terminal width (`screen_x`), the `Table.check_separator` method silently replaces it with a single space and logs an error 【5†L31-L44】. This safety mechanism prevents display corruption in narrow terminal windows.

### How do I set a permanent custom separator for all tables in my project?

Subclass the `Table` class and store your preferred separator in an instance attribute. Override the `render` method to inject this separator via `kwargs.setdefault("separator", self._sep)` before calling `super().render()`. This approach ensures consistency across your application while still allowing per-call overrides.