react-native-quick-filter

A reusable quick-filter flow for React Native & Expo — a horizontal chip / pill bar, chip dropdowns, and a slide-in filter panel with sort, faceted counts, a live result counter, i18n, and light / dark theming. Ships a headless core + a themed, ready-to-use UI. Distilled from the filter UX of Trendyol, Amazon, Flo and MediaMarkt.

Screenshots

| Chip bar + product list | Dropdown (deferred apply) | Master-detail panel (Amazon-style) | Sheet, dark (MediaMarkt-style) | |:---:|:---:|:---:|:---:| | | | | |

Why

Every e-commerce / catalog / search screen re-implements the same filtering UX: a scrollable chip bar, a way to pick values, an Apply step, a live result count, and active filters reflected back on the bar. react-native-quick-filter captures that as one domain-agnostic abstraction you can drop into any app.

• Headless core + themed UI — zero-config out of the box, every part overridable.
• Three detailed-filter presentations sharing one state: drilldown, master-detail (Amazon), and sheet (MediaMarkt).
• Instant (toggle) and deferred (Apply/CTA) apply modes side by side.
• Live result counter (resolveResultCount, sync or async) + faceted per-option counts.
• Strict TypeScript, ships CJS + ESM + .d.ts.
• i18n (English default, Turkish included) and light / dark theming.
• Reanimated slide + swipe-to-dismiss (gesture-handler), reduce-motion aware.
• Expo-friendly — JS-only, no native module; works in Expo Go and dev builds.

Installation

npm install react-native-quick-filter
# or: yarn add react-native-quick-filter  /  pnpm add react-native-quick-filter

Then install the peer dependencies (all in the Expo SDK):

npx expo install react-native-reanimated react-native-gesture-handler react-native-safe-area-context

| peer dependency | version | |---|---| | react | >=18 | | react-native | >=0.74 | | react-native-reanimated | >=3.6 (v3 & v4) | | react-native-gesture-handler | >=2.14 | | react-native-safe-area-context | >=4.8 |

App setup

Wrap your app root once, and make sure the Reanimated Babel plugin is enabled.

// App.tsx
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { SafeAreaProvider } from 'react-native-safe-area-context';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>{/* your app */}</SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

// babel.config.js (bare RN). The Reanimated plugin MUST be last.
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: ['react-native-reanimated/plugin'], // v4: 'react-native-worklets/plugin'
};

With Expo, babel-preset-expo adds the Reanimated/worklets plugin automatically.

Quick start

import { useState } from 'react';
import {
  FilterProvider, QuickFilterBar, FilterDropdown, FilterSidePanel,
  type Facet, type ChipSpec, type Selection,
} from 'react-native-quick-filter';

const facets: Facet[] = [
  { id: 'sort', label: 'Sort', kind: 'single', options: [
      { id: 'recommended', label: 'Recommended' },
      { id: 'priceAsc', label: 'Price: Low to High' },
  ] },
  { id: 'category', label: 'Category', kind: 'multi', searchable: true, selectAll: true,
    options: [{ id: 'shoes', label: 'Shoes' }, { id: 'bags', label: 'Bags' }] },
  { id: 'brand', label: 'Brand', kind: 'multi', searchable: true, columns: 2,
    options: [{ id: 'nike', label: 'Nike' }, { id: 'adidas', label: 'Adidas' }] },
  { id: 'price', label: 'Price', kind: 'range', min: 0, max: 5000,
    presets: [{ id: 'p1', label: '$0 – $300', min: 0, max: 300 }] },
  { id: 'express', label: 'Express Delivery', kind: 'toggle',
    options: [{ id: 'on', label: 'Express Delivery' }] },
];

const chips: ChipSpec[] = [
  { facetId: 'filter', kind: 'action', label: 'Filter', opens: 'sidePanel' },
  { facetId: 'sort', kind: 'dropdown', label: 'Sort' },
  { facetId: 'category', kind: 'dropdown' },
  { facetId: 'brand', kind: 'dropdown' },
  { facetId: 'price', kind: 'dropdown' },
  { facetId: 'express', kind: 'toggle', removable: true },
];

function Screen() {
  const [selection, setSelection] = useState<Selection>();
  return (
    <FilterProvider
      facets={facets}
      chips={chips}
      onSelectionChange={setSelection}
      resolveResultCount={(sel) => fetchCount(sel)} // sync number or Promise<number>
    >
      <QuickFilterBar />
      {/* your product list, filtered by `selection` */}
      <FilterDropdown />
      <FilterSidePanel variant="masterDetail" side="left" />
    </FilterProvider>
  );
}

Detailed filter presentations

All three share the same state — whichever you render is what opens when the Filter chip is triggered.

// 1) drilldown — single panel, group list → tap → detail (with back). (Trendyol)
<FilterSidePanel variant="drilldown" side="right" />

// 2) masterDetail — left rail + right content, both visible at once. (Amazon)
<FilterSidePanel variant="masterDetail" side="left" animated={false} />

// 3) sheet — all facets as collapsible sections, pops over the page. (MediaMarkt)
//    presentation="fullScreen" for full screen; long sections scroll independently.
<FilterSheet presentation="sheet" sectionMaxHeight={280} />

Concepts

• Facet — a filter dimension (single | multi | range | toggle), independent of presentation.
• ChipSpec — a chip in the bar (action | dropdown | toggle | segment).
• Selection — the single source of truth: { options: Record<id, string[]>, ranges: Record<id, { min?, max? }> }.
• applyMode — instant (applies immediately) or deferred (draft → commit via Apply/CTA), per facet or provider-wide.

Theme & i18n

import { ThemeProvider, StringsProvider } from 'react-native-quick-filter';

<ThemeProvider scheme="dark" override={{ colors: { accent: '#F27A1A' } }}>
  <StringsProvider strings={{ apply: 'Apply', resultCount: (n) => `${n} items` }}>
    {/* ... */}
  </StringsProvider>
</ThemeProvider>

Without providers, the light theme + English dictionary defaults apply (zero-config). A Turkish dictionary ships built-in (import { tr } from 'react-native-quick-filter').

Controlled / uncontrolled

Pass a selection prop for controlled mode; omit it and use defaultSelection for uncontrolled. onSelectionChange(next) fires on every commit.

Headless usage

Build your own UI with only hooks — no UI components:

const { selection, activeCount, clearAll } = useFilter();
const brand = useFacet('brand'); // toggleOption, visibleOptions, commit, searchQuery, ...

API

| Category | Exports | |---|---| | Provider | FilterProvider | | Hooks | useFilter, useFacet, useResultCount, useDropdown, usePanel, useChip | | Bar / Chips | QuickFilterBar, QuickFilterChip, Chip | | Dropdown | FilterDropdown | | Detailed filter | FilterSidePanel (variant: drilldown | masterDetail), FilterSheet (presentation: sheet | fullScreen), SidePanelMasterList, SidePanelRail | | Bodies | FacetBody, CheckboxListBody, RadioListBody, RangeBody | | Atoms | ResultCountButton, FilterFooter, Button, Checkbox, Radio, Badge, SearchInput, Chevron | | Theme | ThemeProvider, useTheme, defaultLightTheme, defaultDarkTheme, mergeTheme | | i18n | StringsProvider, useStrings, tr, en, formatNumber | | Types | Facet, FacetOption, ChipSpec, Selection, RangeValue, QuickFilterTheme, QuickFilterStrings, … |

Full reference: docs/API.md · usage guide: docs/USAGE.md · consuming in another project: docs/CONSUMING.md.

For LLM tools (Claude Code, Cursor, GPT, etc.), a condensed machine-readable surface lives in llms.txt.

Compatibility

| | | |---|---| | React Native | >=0.74 (incl. New Architecture — JS-only, no native module) | | Expo | SDK 50+ · Expo Go & dev builds | | Reanimated | v3 (>=3.6) and v4 | | Platforms | iOS · Android · (web via react-native-web, untested) | | Types | Bundled .d.ts (strict) |

Development

npm run typecheck   # tsc --noEmit (strict)
npm test            # jest + @testing-library/react-native (36 tests)
npm run build       # react-native-builder-bob → lib/{module,commonjs,typescript}

Example app (Expo)

Three demos under example/: Store (light, master-detail panel), Electronics (dark, sheet, faceted counts), Headless (hooks only).

cd example
./scripts/sync-lib.sh   # packs & installs the library (re-run after source changes)
npx expo run:ios --device "iPhone 17 Pro Max"   # or: npx expo start

The example consumes the library as an npm pack tarball because it lives inside the package, which breaks Metro's symlink/out-of-tree resolution. A separate consumer app does not hit this — a normal install just works.

Keywords

React Native filter, Expo filter, quick filter, filter bar, filter chips, filter pills, faceted search, facets, sort menu, bottom-sheet filter, side panel / drawer filter, filter dropdown, e-commerce product filter, Trendyol/Amazon/MediaMarkt-style filter UI, headless filter, Reanimated filter.

Contributing

Issues and PRs welcome. Run npm run typecheck && npm test before opening a PR. See CHANGELOG.md for release history.

Design inspiration & analysis: references/00-GENEL-ANALIZ.md and per-app references/*/ANALYSIS.md.

License

MIT © enes ozturk