excel-compose

An Excel-style dense data grid for Compose Multiplatform (Android + Desktop) — resizable columns, click-to-sort headers, per-column filters, row selection, row tinting, and a synced horizontal scroll across header/filter/body. No CompositionLocal theming — colors are plain parameters, the same spirit as Scaffold's containerColor.

English · Türkçe

• Resizable columns — drag a header border like Excel; the rest of the grid doesn't jitter while you drag (only the column you're resizing changes size).
• Optional column stretching — stretchColumns grows not-manually-resized columns to fill leftover width instead of leaving plain background past the last one; off by default.
• Per-column content alignment — GridColumn.contentAlign positions a body cell's content anywhere in its row-height box (any of the 9 Alignment combinations), CenterStart by default.
• Click-to-sort headers — the grid only renders the indicator (▴ ▾ ↕) and reports which column was clicked; you own the actual sorting logic.
• Per-column filters — a plain text box by default, or plug in ChoiceFilterCell / MultiChoiceFilterCell / your own composable.
• Row selection — an optional leading checkbox column with a tri-state "select all".
• Row tinting & dimming — color a row (e.g. by status) or fade it out (e.g. inactive records) with a simple per-row function.
• Editable columns — turn on editable to let users append a column (a "+" button), delete one (a "×" glyph on its header), and long-press-drag to reorder columns, with siblings animating out of the way; each affordance opts in independently, based on which callback you supply.
• Scrollbar visibility — verticalScrollbar/horizontalScrollbar independently pick whether a scrollbar is hidden, shown only while there's actually something to scroll to (the default), or always shown.
• Right-click copy, desktop-only — optional "copy cell" / "copy row" / "copy selected rows" context-menu items alongside the platform's own "Copy", each producing CSV-ish text (a heading line + comma-separated values) ready to paste into a spreadsheet.
• No forced latency on taps — single-tap and double-tap are each only as slow as they need to be; see Tap behavior below.
• No CompositionLocal — every color is an explicit parameter (ExcelGridColors), so there's nothing implicit to wire up in a host app's theme.
• Storage-agnostic — the grid keeps resized column widths in memory and hands you a callback to persist them however you like; it never assumes a specific storage layer.

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

// build.gradle.kts (commonMain)
dependencies {
    implementation("io.github.ridvangnc:excel-compose:<version>")
}

data class Employee(val id: String, val name: String, val department: String, val salary: Int)

val columns = listOf(
    GridColumn<Employee>("name", "Name", 200.dp, sortable = true, value = { it.name }),
    GridColumn("department", "Department", 160.dp, value = { it.department }),
    GridColumn("salary", "Salary", 120.dp, sortable = true, value = { it.salary.toString() }),
)

DataGrid(
    columns = columns,
    rows = employees,
    key = { it.id },
    colors = ExcelGridDefaults.colors(containerColor = Color.White),
    selectable = true,
    selectedKeys = selectedKeys,
    onSelect = { key -> selectedKeys = if (key in selectedKeys) selectedKeys - key else selectedKeys + key },
    onSelectAll = { all -> selectedKeys = if (all) employees.map { it.id }.toSet() else emptySet() },
    sortId = sortId,
    sortDesc = sortDesc,
    onSort = { columnId -> /* flip sortId/sortDesc, re-sort `employees` yourself */ },
    onRowOpen = { row -> /* double-click: open/edit `row` */ },
)

See demo/ for a complete, runnable example (./gradlew :demo:run).

Drag any header border to resize a column, like Excel — only the column you're dragging changes size, the rest hold steady.

Click a sortable header to sort ascending/descending; the indicator (▴ ▾ ↕) shows the current state.

Type in a column's filter box, or use a dropdown (ChoiceFilter/MultiChoiceFilter) for a fixed set of values.

An optional leading checkbox column with a tri-state "select all" in the header.

The grid itself. All parameters have defaults except columns, rows, and key.

data class GridColumn<T>(
    val id: String,
    val heading: String,
    val width: Dp,
    val cell: ExcelComposeCell<T>,
    val filter: ExcelComposeFilter = ExcelComposeFilter.TextFilter,
    val sortable: Boolean = false,
    val align: TextAlign = TextAlign.Start,
    val contentAlign: Alignment = Alignment.CenterStart,
)

// Convenience constructor for the common case — plain text, no need to wrap it yourself:
fun <T> GridColumn(
    id: String, heading: String, width: Dp,
    filter: ExcelComposeFilter = ExcelComposeFilter.TextFilter,
    sortable: Boolean = false, align: TextAlign = TextAlign.Start,
    contentAlign: Alignment = Alignment.CenterStart,
    value: (T) -> String,
): GridColumn<T>

• width is the column's on-screen width (or its starting width, if the user resizes it) — columns render at exactly this width and never stretch to fill extra space by default; a grid wider than its columns' combined width just shows plain background past the last one, and a grid narrower than that sum scrolls horizontally instead. Set DataGrid's own stretchColumns = true to grow not-manually-resized columns proportionally into that leftover space instead.
• cell picks what the cell body renders — see ExcelComposeCell below. Most columns just pass value = { ... } and never touch cell directly; that goes through the convenience constructor.
• filter picks what the filter-row box looks like — see ExcelComposeFilter below.
• contentAlign positions this column's BODY cell content (any Alignment, e.g. Alignment.TopEnd) within its full row-height box — Alignment.CenterStart (left-aligned, vertically centered) by default. Unrelated to align (TextAlign), which only affects a TextCell's own horizontal text alignment. Header/filter cells are unaffected — this is body rows only.

A typed alternative to a loose value: (T) -> String + nullable content: @Composable (T) -> Unit pair, same spirit as ExcelComposeFilter:

sealed interface ExcelComposeCell<T> {
    data class TextCell<T>(val value: (T) -> String) : ExcelComposeCell<T>
    data class CustomCell<T>(val content: @Composable (T) -> Unit, val copyValue: ((T) -> String)? = null) : ExcelComposeCell<T>
}

copyValue is CustomCell's optional plain-text stand-in — supply it so copyCellLabel/copyRowLabel/copySelectedRowsLabel (see Copy to clipboard) have something to copy for a column that otherwise renders arbitrary composables; left null (the default), that column is simply skipped by all three, the same as not configuring them at all.

GridColumn(
    id = "salary", heading = "Salary", width = 120.dp,
    cell = ExcelComposeCell.CustomCell(
        content = { employee ->
            Row {
                Text(employee.salary.toString())
                if (employee.salary >= 95000) Text(" ★", color = Color(0xFFB8860B))
            }
        },
        copyValue = { it.salary.toString() },
    ),
)

data class ExcelGridColors(
    val containerColor: Color,
    val headerContainerColor: Color,
    val filterContainerColor: Color,
    val rowContainerColor: Color,
    val selectedRowContainerColor: Color,
    val dimmedRowContainerColor: Color,
    val lineColor: Color,
    val filterBorderColor: Color,
    val selectedBorderColor: Color,
)

No CompositionLocal — just pass an ExcelGridColors in. ExcelGridDefaults.colors(...) gives you sensible Material 3-derived defaults for any subset you don't override, e.g.:

ExcelGridDefaults.colors(containerColor = MyBrand.background, selectedRowContainerColor = MyBrand.accent)

A typed, discoverable choice for a column's filter — instead of a loose filterable: Boolean + nullable @Composable lambda pair, pick a named case:

sealed interface ExcelComposeFilter {
    data object NoFilter : ExcelComposeFilter
    data object TextFilter : ExcelComposeFilter
    data class ChoiceFilter(val options: List<Pair<String, String>>) : ExcelComposeFilter
    data class MultiChoiceFilter(val options: List<Pair<String, String>>, val allLabel: String) : ExcelComposeFilter
    data class CustomFilter(val content: @Composable (current: String, onChange: (String) -> Unit) -> Unit) : ExcelComposeFilter
}

GridColumn(
    "department", "Department", 160.dp, value = { it.department },
    filter = ExcelComposeFilter.ChoiceFilter(
        listOf("" to "All", "Engineering" to "Engineering", "Research" to "Research"),
    ),
)

ChoiceFilterCell/MultiChoiceFilterCell (the composables backing ChoiceFilter/MultiChoiceFilter) are also exported directly, in case you want to reuse them outside of a GridColumn.

There is no way to tell a single click from the first half of a double click without either waiting to see if a second tap follows, or accepting that a double click also fires the single-tap action once before the double-tap action. DataGrid only pays that cost when it actually has to:

singleTapEnabled defaults to selectable || openOnSingleTap (i.e., true only when the grid actually does something on a single tap); override it explicitly if you rely purely on onRowTap for single-tap behavior. doubleTapTimeoutMillis defaults to 300L.

The grid keeps resized widths in memory for its own lifetime. To persist them across app restarts, load your own saved widths into initialColumnWidths and save whatever onColumnWidthChange reports — the library has no opinion on how you store it (a file, a database, SharedPreferences, anything).

editable turns on column-editing affordances — each one only renders while its own callback below is also non-null, so you opt into exactly the subset you want:

DataGrid(
    columns = columns,
    rows = employees,
    key = { it.id },
    editable = true,
    onAddColumn = { /* append a new GridColumn to your own `columns` list */ },
    onDeleteColumn = { columnId -> columns = columns.filterNot { it.id == columnId } },
    onReorder = { from, to -> columns = columns.toMutableList().apply { add(to, removeAt(from)) } },
)

• Add — a "+" button pinned to the header's top-right corner, always reachable by scrolling regardless of how wide the grid's columns are.
• Delete — a "×" glyph next to each header's label.
• Reorder — long-press a header and drag; siblings reflow out of the way (animateColumnReorder/columnReorderAnimationMillis control that reflow animation), and a selection outline follows the dragged column across the header, filter row, and every currently visible body row.

sealed interface ScrollbarVisibility {
    data object Hidden : ScrollbarVisibility
    data object Overflow : ScrollbarVisibility
    data object Visible : ScrollbarVisibility
}

verticalScrollbar/horizontalScrollbar each pick one, independently — Overflow (the default for both) only draws a scrollbar while there's actually something to scroll to in that direction, which is what you want on a short grid that shouldn't show a spurious full-track thumb.

DataGrid(
    columns = columns,
    rows = employees,
    key = { it.id },
    selectable = true,
    selectedKeys = selectedKeys,
    // ...
    copyCellLabel = "Copy cell",
    copyRowLabel = "Copy row",
    copySelectedRowsLabel = "Copy selected rows",
)

Adds up to three extra items to the right-click context menu that's already there for selected text (which otherwise just shows "Copy"):

Each label defaults to null, which leaves that item out entirely, at no extra cost. All three are desktop-only — there's no right-click on touch, so they have no effect on Android.

MIT — see LICENSE.

• Kolon genişliği ayarlanabilir — Excel'deki gibi başlık sınırından sürükle; sürüklerken diğer kolonlar titremiyor (sadece sürüklediğin kolon boyut değiştiriyor).
• Opsiyonel kolon büyütme — stretchColumns, elle boyutlandırılmamış kolonları boş alanı doldurmak için büyütür (son kolondan sonra düz arka plan bırakmak yerine); varsayılan kapalı.
• Kolon bazlı içerik hizalama — GridColumn.contentAlign, gövde hücresinin içeriğini satır-yüksekliğindeki kutu içinde istediğin yere konumlandırır (9 Alignment kombinasyonundan biri), varsayılan CenterStart.
• Başlığa tıklayarak sıralama — grid yalnızca ok göstergesini (▴ ▾ ↕) çiziyor ve hangi kolona tıklandığını bildiriyor; asıl sıralama mantığı sende.
• Kolon bazlı filtreler — varsayılan olarak düz metin kutusu, istersen ChoiceFilterCell / MultiChoiceFilterCell ya da kendi composable'ını bağlarsın.
• Satır seçimi — opsiyonel, sol başta üç durumlu ("hepsini seç") checkbox kolonu.
• Satır renklendirme ve soluklaştırma — bir satırı (örn. duruma göre) renklendir ya da (örn. pasif kayıtlar için) soluklaştır, basit bir satır-bazlı fonksiyonla.
• Düzenlenebilir kolonlar — editable'ı açarak kullanıcıların kolon eklemesine ("+" düğmesi), silmesine (başlıkta "×" işareti) ve basılı tutup sürükleyerek yeniden sıralamasına izin ver; diğer kolonlar yer açmak için animasyonla kayar. Her biri, ilgili callback'i verdiğin ölçüde ayrı ayrı devreye girer.
• Scrollbar görünürlüğü — verticalScrollbar/horizontalScrollbar birbirinden bağımsız olarak scrollbar'ın hiç gösterilmemesini, yalnızca gerçekten kaydıracak bir şey varken gösterilmesini (varsayılan) ya da her zaman gösterilmesini seçer.
• Sağ tıkla kopyalama, yalnızca masaüstü — platformun kendi "Copy"sinin yanına opsiyonel "hücreyi kopyala" / "satırı kopyala" / "seçili satırları kopyala" seçenekleri; her biri bir tabloya yapıştırılabilir CSV benzeri metin (başlık satırı + virgülle ayrılmış değerler) üretiyor.
• Dokunmada zorunlu gecikme yok — tek ve çift tıklama, sadece gerçekten gerektiği kadar yavaş; aşağıdaki Dokunma davranışı bölümüne bak.
• CompositionLocal yok — her renk açık bir parametre (ExcelGridColors), uygulamanın temasına örtük bir şekilde bağlanan hiçbir şey yok.
• Depolamadan bağımsız — grid, sürükleyerek değiştirilen kolon genişliklerini bellekte tutar ve sana bir callback verir; nasıl saklayacağın (dosya, veritabanı, her neyse) tamamen sana kalmış.

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

// build.gradle.kts (commonMain)
dependencies {
    implementation("io.github.ridvangnc:excel-compose:<sürüm>")
}

data class Employee(val id: String, val name: String, val department: String, val salary: Int)

val columns = listOf(
    GridColumn<Employee>("name", "Name", 200.dp, sortable = true, value = { it.name }),
    GridColumn("department", "Department", 160.dp, value = { it.department }),
    GridColumn("salary", "Salary", 120.dp, sortable = true, value = { it.salary.toString() }),
)

DataGrid(
    columns = columns,
    rows = employees,
    key = { it.id },
    colors = ExcelGridDefaults.colors(containerColor = Color.White),
    selectable = true,
    selectedKeys = selectedKeys,
    onSelect = { key -> selectedKeys = if (key in selectedKeys) selectedKeys - key else selectedKeys + key },
    onSelectAll = { all -> selectedKeys = if (all) employees.map { it.id }.toSet() else emptySet() },
    sortId = sortId,
    sortDesc = sortDesc,
    onSort = { columnId -> /* sortId/sortDesc'i çevir, `employees`'i kendin yeniden sırala */ },
    onRowOpen = { row -> /* çift tıklama: `row`'u aç/düzenle */ },
)

Tam, çalıştırılabilir bir örnek için demo/'ya bak (./gradlew :demo:run).

Excel'deki gibi herhangi bir başlık sınırını sürükleyerek kolonu boyutlandır — sadece sürüklediğin kolon değişir, diğerleri yerinde kalır.

Sıralanabilir bir başlığa tıkla, artan/azalan sıralanır; gösterge (▴ ▾ ↕) o anki durumu gösterir.

Bir kolonun filtre kutusuna yaz, ya da sabit bir değer kümesi için açılır liste (ChoiceFilter/MultiChoiceFilter) kullan.

Başlıkta üç durumlu "hepsini seç" içeren opsiyonel, sol başta bir checkbox kolonu.

Grid'in kendisi. columns, rows, key dışındaki tüm parametrelerin varsayılan değeri var.

data class GridColumn<T>(
    val id: String,
    val heading: String,
    val width: Dp,
    val cell: ExcelComposeCell<T>,
    val filter: ExcelComposeFilter = ExcelComposeFilter.TextFilter,
    val sortable: Boolean = false,
    val align: TextAlign = TextAlign.Start,
    val contentAlign: Alignment = Alignment.CenterStart,
)

// Yaygın durum için kolaylık constructor'ı — düz metin, kendin sarmalamana gerek yok:
fun <T> GridColumn(
    id: String, heading: String, width: Dp,
    filter: ExcelComposeFilter = ExcelComposeFilter.TextFilter,
    sortable: Boolean = false, align: TextAlign = TextAlign.Start,
    contentAlign: Alignment = Alignment.CenterStart,
    value: (T) -> String,
): GridColumn<T>

• width kolonun ekrandaki genişliğidir (kullanıcı yeniden boyutlandırırsa, başlangıç genişliği) — kolonlar varsayılan olarak tam bu genişlikte çizilir, boşluğu doldurmak için büyümez; grid, kolonların toplam genişliğinden daha genişse son kolondan sonrasında düz arka plan gösterir, daha darsa yatay kayar. DataGrid'in stretchColumns = true'unu ayarlayarak elle boyutlandırılmamış kolonları o boşluğu doldurmak üzere orantılı büyütebilirsin.
• cell, hücre gövdesinin neyi çizeceğini seçer — aşağıdaki ExcelComposeCell'e bak. Çoğu kolon sadece value = { ... } verir, cell'e hiç dokunmaz — bu, kolaylık constructor'ından geçer.
• filter, filtre satırındaki kutunun neye benzeyeceğini seçer — aşağıdaki ExcelComposeFilter'e bak.
• contentAlign, bu kolonun GÖVDE hücrelerinin (başlık/filtre değil) içeriğini tam satır-yüksekliğindeki kutu içinde nasıl konumlandıracağını belirler (herhangi bir Alignment, ör. Alignment.TopEnd) — varsayılan Alignment.CenterStart (sola dayalı, dikeyde ortalı). align (TextAlign) ile ilgisi yoktur — o yalnızca bir TextCell'in kendi yatay metin hizasını etkiler.

Gevşek bir value: (T) -> String + nullable content: @Composable (T) -> Unit ikilisine tipli bir alternatif, ExcelComposeFilter ile aynı ruhta:

sealed interface ExcelComposeCell<T> {
    data class TextCell<T>(val value: (T) -> String) : ExcelComposeCell<T>
    data class CustomCell<T>(val content: @Composable (T) -> Unit, val copyValue: ((T) -> String)? = null) : ExcelComposeCell<T>
}

copyValue, CustomCell'in opsiyonel düz-metin karşılığıdır — copyCellLabel/copyRowLabel/copySelectedRowsLabel'ın (bkz. Panoya kopyalama) kopyalayacak bir şeyi olsun diye verilir; null bırakılırsa (varsayılan), o kolon üçü tarafından da tamamen atlanır — hiç yapılandırılmamış gibi.

GridColumn(
    id = "maas", heading = "Maaş", width = 120.dp,
    cell = ExcelComposeCell.CustomCell(
        content = { calisan ->
            Row {
                Text(calisan.maas.toString())
                if (calisan.maas >= 95000) Text(" ★", color = Color(0xFFB8860B))
            }
        },
        copyValue = { it.maas.toString() },
    ),
)

data class ExcelGridColors(
    val containerColor: Color,
    val headerContainerColor: Color,
    val filterContainerColor: Color,
    val rowContainerColor: Color,
    val selectedRowContainerColor: Color,
    val dimmedRowContainerColor: Color,
    val lineColor: Color,
    val filterBorderColor: Color,
    val selectedBorderColor: Color,
)

CompositionLocal yok — sadece bir ExcelGridColors geç. ExcelGridDefaults.colors(...), override etmediğin her alan için Material 3 tabanlı makul varsayılanlar verir, örn.:

ExcelGridDefaults.colors(containerColor = MarkamRengim.zemin, selectedRowContainerColor = MarkamRengim.vurgu)

Bir kolonun filter'ı için tip-güvenli, keşfedilebilir bir seçim — gevşek bir filterable: Boolean + nullable @Composable lambda ikilisi yerine, isimli bir case seçiyorsun:

sealed interface ExcelComposeFilter {
    data object NoFilter : ExcelComposeFilter
    data object TextFilter : ExcelComposeFilter
    data class ChoiceFilter(val options: List<Pair<String, String>>) : ExcelComposeFilter
    data class MultiChoiceFilter(val options: List<Pair<String, String>>, val allLabel: String) : ExcelComposeFilter
    data class CustomFilter(val content: @Composable (current: String, onChange: (String) -> Unit) -> Unit) : ExcelComposeFilter
}

GridColumn(
    "bolge", "Bölge", 160.dp, value = { it.bolge },
    filter = ExcelComposeFilter.ChoiceFilter(
        listOf("" to "Hepsi", "Bornova" to "Bornova", "Kemalpaşa" to "Kemalpaşa"),
    ),
)

ChoiceFilterCell/MultiChoiceFilterCell (ChoiceFilter/MultiChoiceFilter'ın arkasındaki composable'lar) doğrudan da dışa açık — bir GridColumn dışında tekrar kullanmak istersen.

Bir ikinci dokunuşun gelip gelmeyeceğini beklemeden, ya da çift tıklamanın tek-tıklama etkisini bir kez tetikleyip tetiklemediğini kabul etmeden, tek tıklamayı çift tıklamanın ilk yarısından ayırmanın bir yolu yok. DataGrid bu bedeli yalnızca gerçekten gerektiğinde ödüyor:

singleTapEnabled varsayılan olarak selectable || openOnSingleTap (yani grid tek dokunuşta gerçekten bir şey yapıyorsa true); tek-tıklama davranışını sadece onRowTap üzerinden yürütüyorsan elle true yap. doubleTapTimeoutMillis varsayılanı 300L.

Grid, sürükleyerek ayarlanan genişlikleri kendi yaşam süresi boyunca bellekte tutar. Uygulama yeniden başlatıldığında da kalıcı olsun istiyorsan, kendi kaydettiğin genişlikleri initialColumnWidths'e yükle, onColumnWidthChange'in bildirdiğini de istediğin yere kaydet — kütüphanenin nasıl sakladığın konusunda hiçbir görüşü yok (dosya, veritabanı, SharedPreferences, ne olursa).

editable, kolon düzenleme özelliklerini açar — her biri yalnızca ilgili callback de null değilse devreye girer, yani tam istediğin alt kümeyi seçebilirsin:

DataGrid(
    columns = columns,
    rows = calisanlar,
    key = { it.id },
    editable = true,
    onAddColumn = { /* kendi `columns` listene yeni bir GridColumn ekle */ },
    onDeleteColumn = { columnId -> columns = columns.filterNot { it.id == columnId } },
    onReorder = { from, to -> columns = columns.toMutableList().apply { add(to, removeAt(from)) } },
)

• Ekleme — başlığın sağ üst köşesine sabitlenmiş bir "+" düğmesi; grid'in kolonları ne kadar geniş olursa olsun kaydırarak her zaman ulaşılabilir.
• Silme — her başlığın etiketinin yanında bir "×" işareti.
• Yeniden sıralama — bir başlığı basılı tutup sürükle; diğer kolonlar yer açmak için kayar (animateColumnReorder/columnReorderAnimationMillis bu kayma animasyonunu kontrol eder), sürüklenen kolonu başlık, filtre satırı ve o an ekranda görünen tüm gövde satırları boyunca bir seçim çerçevesi takip eder.

sealed interface ScrollbarVisibility {
    data object Hidden : ScrollbarVisibility
    data object Overflow : ScrollbarVisibility
    data object Visible : ScrollbarVisibility
}

verticalScrollbar/horizontalScrollbar birbirinden bağımsız olarak birini seçer — Overflow (ikisinin de varsayılanı) yalnızca o yönde gerçekten kaydıracak bir şey varken scrollbar çizer; kısa bir grid'de boş yere tam-dolu bir thumb göstermemek için istediğin de bu.

DataGrid(
    columns = columns,
    rows = calisanlar,
    key = { it.id },
    selectable = true,
    selectedKeys = selectedKeys,
    // ...
    copyCellLabel = "Hücreyi kopyala",
    copyRowLabel = "Satırı kopyala",
    copySelectedRowsLabel = "Seçili satırları kopyala",
)

Seçili metin için zaten var olan sağ-tık context menu'süne (aksi halde sadece "Copy" gösterir) en fazla üç ekstra öğe ekler:

Her etiketin varsayılanı null'dır, bu da o öğeyi hiç eklemez — hiçbir ekstra maliyeti yoktur. Üçü de yalnızca masaüstünde çalışır — dokunmatik ekranlarda sağ tık olmadığı için Android'de hiçbir etkileri yoktur.

MIT — bkz. LICENSE.