> For the complete documentation index, see [llms.txt](https://postica.gitbook.io/binding-system-3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://postica.gitbook.io/binding-system-3/pipeline/converters.md). # Converters Changing the type between the source and the field. A converter changes the **type** of a value, and that is the whole of its job. It is the only stage of the pipeline you will often not notice, because most of the time the right one is found for you. {% hint style="warning" %} **A converter always goes from one type to a different type.** `IConverter` with `TFrom` and `TTo` the same is not a conversion and is never invoked: when the two ends of a binding already agree on the type, the pipeline builds no converter stage at all. Changing a value while keeping its type, scaling it, clamping it, remapping it, converting meters to feet, is a [modifier](/binding-system-3/pipeline/modifiers.md). That distinction is the one thing worth getting right about this page: **converters cross type boundaries, modifiers work inside one.** {% endhint %} ## Automatic conversion Bind a `float` to a `string` field and the system finds the conversion, applies it and says nothing. Numeric widening, Unity type conversions, enum coercions, `ToString` and the rest are resolved from a registry keyed by the pair of types. You see a converter in the Inspector in three cases: 1. **It has options.** A format string, a fallback colour, an enum mapping. 2. **There is more than one candidate**, so somebody has to choose. 3. **You picked one deliberately**, replacing the automatic choice. The converters toggle on the bind row shows or hides the **Read Converter** and **Write Converter** fields.

A binding with a Format String read converter

## Read and write converters A `ReadWrite` binding needs both directions, and they are separate objects, because a conversion is rarely symmetrical. `float` to `string` on the read side pairs with `string` to `float` on the write side, and the two have different options: a format on one, a fallback and a culture on the other. ## Safe and unsafe Every converter declares whether it is **safe**.
SafeWhat it means
YesThe conversion always succeeds, whatever the input. float to string, int to float.
NoThe conversion can fail on some inputs. string to Color, string to float.
An unsafe converter is not a problem, it is a fact about the data. Most of them take a **fallback** value for the failing case, which is where the design pays off: the binding does not throw and does not log a stream of errors, it gives you the fallback. ## What ships in the box
ConverterWhat it does
Format StringAny IFormattable to string, with a format passed to ToString and an invariant-culture switch. Caches its last result.
String to Decimalstring to any numeric type.
Decimal to IntegerRounding between numeric types.
String to ColorColour names (red, White), hex (#2e34f3, 33BBEF) and RGBA(0.14, 0.94, 0.65, 0.5), with a fallback colour.
Gradient To ColorSamples a Gradient at a position.
Color to GradientA Color into a Gradient. Each stop of the gradient takes the colour, tinted if wanted, or a colour of its own, so the colour can sit anywhere along it. By default the whole gradient is the colour. Allocates nothing as the colour changes.
Booleanbool to almost anything: numbers, strings, vectors, colours.
Numeric to BoolThe other direction, with a threshold.
Numeric to VectorA number into a Vector2, Vector3 or Vector4 component.
Enum convertersenum to and from numbers and strings, with an explicit mapping editor. Works with typed and untyped enums.
List / ArrayBetween List<T> and T[].
StringBuilder to StringFor text built incrementally.
Char Array to String and backMainly for TextMeshPro, which exposes text as a char[].
Unity EventLets a UnityEvent participate as a binding target.
The enum converter has its own editor, so mapping `Difficulty.Hard` to `2` or to `"hard"` is a table you fill in rather than code you write.

The enum converter mapping editor

## Saving one A converter you have filled in can be saved under a name and offered back in every binding whose conversion it can perform. **Window ▸ Binding System ▸ Templates ▸ Converters**. See [Templates](/binding-system-3/pipeline/templates.md#converters). ## Writing one Two properties and one method. The types have to differ, so pick a real conversion: here a duration in seconds becomes a clock string, which the built-in **Format String** converter cannot express. ```csharp using System; using UnityEngine; using Postica.BindingSystem; [Serializable] public class SecondsToClockConverter : IConverter { public string Id => "Seconds to Clock"; public string Description => "Formats a duration in seconds as m:ss."; public bool IsSafe => true; public string Convert(float value) { var total = Mathf.Max(0, Mathf.FloorToInt(value)); return $"{total / 60}:{total % 60:00}"; } } ``` Bind a `float` countdown to a `TMP_Text.text` field, pick this converter on the read side, and the label reads `1:07`. Mark it `[Serializable]` so Unity can store it, add public fields for anything the user should configure (they are drawn in the Inspector, and they can be `Bind` fields themselves), and it is picked up automatically. {% hint style="info" %} If you find yourself writing `IConverter`, you want a [modifier](/binding-system-3/pipeline/modifiers.md) instead. A modifier has the same shape, is drawn in the same place, stacks with others, and can declare an inverse for the write direction. {% endhint %} See [Custom Converters](/binding-system-3/reference/extending/converters.md) for registration, templates, generics and the untyped form. ## Registration Custom converters are found and registered for you when **Auto Register Converters** is on, which it is by default. The scan runs on import and after an upgrade. To register explicitly, for example for a converter built at runtime: ```csharp ConvertersFactory.Register(new SecondsToClockConverter()); // Or from a lambda, when there is nothing to configure ConvertersFactory.Register("Magnitude", v => v.magnitude); ``` Both type arguments are required, and they must differ. Registering a converter whose two types are the same has no effect, because no binding ever asks for that pair. ## Related pages * [Modifiers](/binding-system-3/pipeline/modifiers.md): changing the value rather than the type. If the type does not change, this is the page you want. * [Custom Converters](/binding-system-3/reference/extending/converters.md): the full extension story. * [TextMeshPro and Unity UI](/binding-system-3/reference/integrations/unity-ui.md): the conversions those types need.