` container and since that is the main cell container, you can add multiple Formatters to add/remove multiple CSS classes on that same container.
```ts
export interface FormatterResultObject {
addClasses?: string;
removeClasses?: string;
text: string;
toolTip?: string;
}
```
**Example of a Custom Formatter with HTML string**
For example, we will use our optional SVG icons `.mdi` with a `boolean` as input data, and display a (fire) icon when `True` or a (snowflake) when `False`. This custom formatter is actually display in the [UI sample](#ui-sample) shown below.
```ts
// create a custom Formatter with the Formatter type
const myCustomCheckboxFormatter: Formatter = (row: number, cell: number, value: any, columnDef: Column, dataContext: any) =>
value ? `
` : '
';
```
**Example with `FormatterResultObject` instead of a string**
Using this object return type will provide the user the same look and feel, it will actually be quite different. The major difference is that all of the options (`addClasses`, `tooltip`, ...) will be added the CSS container of the cell instead of the content of that container. For example a typically cell looks like the following `
Task 4
` and if use `addClasses: 'red'`, it will end up being `
Task 4
` while if we use a string output of let say `
${value>`, then our final result of the cell will be `
Task 4
`. This can be useful if you plan to use multiple Formatters and don't want to lose or overwrite the previous Formatter result (we do that in our project).
```ts
// create a custom Formatter and returning a string and/or an object of type FormatterResultObject
const myCustomCheckboxFormatter: Formatter = (row: number, cell: number, value: any, columnDef: Column, dataContext: any, grid?: any) =>
value ? { addClasses: 'mdi mdi-fire', text: '', tooltip: 'burning fire' } : '
';
```
**Example of Custom Formatter with Native DOM Element**
Since version 4.x, you can now also return native DOM element instead of an HTML string. There are 2 main reasons for going with this approach:
1. CSP Safe by default, since it's native it is 100% CSP Safe (CSP: Content Security Policy)
2. Performance (the reasons are similar to point 1.)
* since it's native it can be appended directly to the grid cell
* when it's an HTML string, it has to do 2 extra steps (which is an overhead process) i. sanitize the string (when a sanitizer, for example [DOMPurify](https://github.com/cure53/DOMPurify)) ii. SlickGrid then has to convert it to native element by using `innerHTML` on the grid cell
Demo
```ts
export const iconFormatter: Formatter = (_row, _cell, _value, columnDef) => {
const iconElm = document.createElement('span');
iconElm.className = 'mdi mdi-check';
return iconElm;
};
```
> **Note** you could also use our helper `createDomElement` which allows to create a DOM element and pass properties like `className` in 1 liner (and it also works with intellisense). For example `createDomElement('span', { className: 'bold title', textContent: 'Hello World', title: 'some tooltip description' })` would equal to 4 lines of code.
**More Complex Example**
If you need to add more complex logic to a `Formatter`, you can take a look at the [percentCompleteBar](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/formatters/percentCompleteBarFormatter.ts) `Formatter` for more inspiration.
**Common Formatter Options**
You can set some defined common Formatter Options in your Grid Options through the `formatterOptions` in the Grid Options (locally or globally) as seen below, and/or independently through the column definition `params` (the option names are the same in both locations)
```ts
loadGrid() {
this.columns = [
// through the column definition "params"
{ id: 'price', field: 'price', params: { thousandSeparator: ',' } },
];
// or through grid options to make it global
this.gridOptions = {
autoResize: {
containerId: 'demo-container',
sidePadding: 15
},
enableAutoResize: true,
// you customize the date separator through "formatterOptions"
formatterOptions: {
// What separator to use to display a Date, for example using "." it could be "2002.01.01"
dateSeparator: '/', // can be any of '/' | '-' | '.' | ' ' | ''
// Defaults to dot ".", separator to use as the decimal separator, example $123.55 or $123,55
decimalSeparator: ',', // can be any of '.' | ','
// Defaults to false, option to display negative numbers wrapped in parentheses, example: -$12.50 becomes ($12.50)
displayNegativeNumberWithParentheses: true,
// Defaults to undefined, minimum number of decimals
minDecimal: 2,
// Defaults to undefined, maximum number of decimals
maxDecimal: 4,
// Defaults to undefined, add a prefix when using `Formatters.decimal` (only) which can be used for example to display a currency.
// output: € 123.45'
numberPrefix: '€ ',
// Defaults to undefined, add a suffix when using `Formatters.decimal` (only) which can be used for example to display a currency.
// output: '123.45 €'
numberSuffix: ' €',
// Defaults to empty string, thousand separator on a number. Example: 12345678 becomes 12,345,678
thousandSeparator: '_', // can be any of ',' | '_' | ' ' | ''
},
}
}
```
**Custom Date Formatter**
There many built-in Date Formatters that are already available (see [list](#list-of-provided-formatters) above), but sometime those are not sufficient and perhaps you wish to use your own custom date format. For these times, the `Formatters.date` can come handy (which is a base Date Formatter), it allows to provide a custom format via `params.dateFormat`.
For example, if you wish to display a date like `"March 12, 2025"`, you could add this to your column definition:
```ts
const columns = [
{
id: 'finish', name: 'Finish', field: 'finish',
type: 'date',
formatter: Formatters.date,
params: { dateFormat: 'MMM DD, YYYY' }
}
];
```
> **Note** all Date formatters are formatted using [Tempo](https://tempo.formkit.com/#format-tokens) tokens. Visit their website to find out which format to use.
**PostRender Formatter (async)**
SlickGrid also support Post Render Formatter (asynchronously) via the Column property `asyncPostRender` (you will also need to enable in the grid options via `enableAsyncPostRender`). When would you want to use this? It's useful if your formatter is expected to take a while to render, like showing a graph with Sparklines, and you don't want to delay rendering your grid, the Post Render will happen after all the grid is loaded.
To see it in action, from the 6pac samples, click [here](http://6pac.github.io/SlickGrid/examples/example10-async-post-render.html) Code example:
```ts
const renderSparklineFormatter: Formatter = (row: number, cell: number, value: any, columnDef: Column, dataContext: any) => {
var vals = [
dataContext['n1'],
dataContext['n2'],
dataContext['n3'],
dataContext['n4'],
dataContext['n5']
];
$(cellNode).empty().sparkline(vals, { width: '100%' });
}
defineGrid() {
this.columns = [
{ id: 'title', name: 'Title', field: 'title' },
{ id: 'chart', name: 'Chart', sortable: false, width: 60,
formatter: waitingFormatter,
rerenderOnResize: true,
asyncPostRender: renderSparklineFormatter
}
];
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://ghiscoding.gitbook.io/slickgrid-universal/column-functionalities/formatters.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.