Upgrading

One section per release, newest first, with only the changes that need action from you. The full record of every release, features and fixes included, is on GitHub releases.

Unreleased: date filters compare whole days

DataView, DataTable and FilterChip read and compare dates as calendar days, without dayjs. A date filter's control is CalendarPreview instead of DatePicker. Calendar, DatePicker and RangePicker are still exported and do not change.

1. Check how your backend reads stringValue

A date filter's stringValue is a day key, '2026-08-15'. It used to be local midnight as a UTC instant, '2026-08-14T18:30:00.000Z' for a viewer in India. value does not change.

1// Before
2onTableQueryChange={query => {
3  // '2026-08-14T18:30:00.000Z'
4  const day = query.filters?.[0]?.stringValue?.slice(0, 10); // '2026-08-14'
5}}
6
7// After
8onTableQueryChange={query => {
9  const day = query.filters?.[0]?.stringValue; // '2026-08-15'
10}}

If your backend took the date part of the old string, it read the day before for every viewer east of UTC. The new value fixes that. A backend that expects a full timestamp may read a date-only string differently, so test it.

Saved filters and URL parameters that hold an old timestamp still load, as the day that instant falls on in the viewer's time zone.

2. Move calendarProps to CalendarPreview props

FilterChip's calendarProps and DataTable's filterProps.calendar take CalendarPreview props now. slotProps.popover and showCalendarIcon work as before. slotProps.input takes CalendarPreview.Input props, which have no value or defaultValue. onErrorChange still reports 'Invalid date', but the error clears only when the typed text is valid or empty, or a date is committed. Closing the popup does not clear it.

1// Before
2<FilterChip
3  columnType="date"
4  calendarProps={{
5    dateFormat: "YYYY-MM-DD",
6    slotProps: { calendar: { disabled: { after: new Date() } } }
7  }}
8/>
9
10// After
11<FilterChip
12  columnType="date"
13  calendarProps={{
14    formatValue: (date, timeZone) =>
15      date.toLocaleDateString("en-CA", { timeZone }),
16    maxDate: new Date()
17  }}
18/>

formatValue changes only the label. The input still reads typed text in the default formats, such as 15 Aug 2026.

3. Handle a cleared date

A date filter can be cleared: click the selected day, or empty the input. The chip then calls onValueChange with ''. In DataView and DataTable the chip stays, and the filter stops matching until a date is picked again. If you render FilterChip yourself, handle ''.

4. Expect different rows from some filters

These filters used to match by mistake, and now match differently:

• A date filter with no value used to filter to today. It is now dropped.
• A date filter passed in query used to filter to today. It now filters by its own date.
• A date filter on a day that does not exist, such as 2026-02-30, used to roll over to 2 March. It is now dropped.
• A row with no date used to be read as today, so it could match any operator, depending on the filter day. It now matches only neq.
• A row holding a day that does not exist used to roll over to a real date. It now matches only neq, and the timeline does not draw it.
• A row holding a numeric string or a boolean used to be read as a date, such as the year 1792 for '1786752000000'. It now matches only neq, and the timeline does not draw it.

2.0: Theme is rewritten

Theme used to put its tokens on <html> from an effect, so it could not server-render and only one could exist per page. It now mounts them on an element it renders, which makes a scope, a portalled popup and the root the same component, and adds radius, scaling, panel background and reduced-motion settings. See Theme.

The component keeps its name but not its props, so migrate the whole application at once rather than file by file.

1. Reshape the props

1// Before
2<Theme
3  defaultTheme="system"
4  storageKey="theme"
5  style="modern"
6  accentColor="orange"
7  grayColor="mauve"
8  onThemeChange={(theme, resolved) => track(resolved)}
9>
10  <App />
11</Theme>
12
13// After
14<Theme
15  persistKey="theme"
16  defaultValue={{
17    appearance: "system",
18    accentColor: "orange",
19    grayColor: "mauve"
20  }}
21  onValueChange={(value, changed) => {
22    if (changed.appearance) track(value.appearance);
23  }}
24>
25  <App />
26</Theme>

persistKey now gates persistence rather than only naming it: without one, nothing is stored. It also ignores the bare theme name the old Theme wrote, so a returning user starts from the seed once.

2. Rename the props

icons is unchanged, and ThemeSwitcher keeps its name.

style="modern" | "traditional" becomes a radius level plus a font pair: defaultValue={{ radius: "large" }} with --rs-font-title and --rs-font-body set in CSS. The data-style attribute and the Lora / Josefin Sans pairing it selected are gone, along with the --rs-font-lora and --rs-font-josefin-sans tokens.

3. Reshape the hook

useTheme keeps its name and returns a different shape.

1// Before: force dark for a subtree
2<Theme forcedTheme="dark"><Sidebar /></Theme>
3// After
4<Theme value={{ appearance: "dark" }}><Sidebar /></Theme>
5
6// Before: flip the page theme from inside a scope
7const { setTheme } = useTheme({ storageKey: "theme" });
8// After
9const { root } = useTheme();
10root.setValue({ appearance: "dark" });

useTheme throws outside a provider instead of returning a no-op.

4. Move anything that reads tokens inside the provider

Tokens are no longer on <html>, so consumer CSS that declared custom properties on :root from --rs-* values, and hand-rolled portals that rendered outside the provider, have to move inside it. <html> no longer needs suppressHydrationWarning.

1.6: lucide replaces the radix icons

Apsara used to draw its icons with @radix-ui/react-icons. Since 1.6 it draws them with lucide, behind stable keys you can replace one at a time.

Some icons look different, lucide-react is a new peer dependency, and the names @raystack/apsara/icons exports have changed.

1. Install the peer dependency

1npm install lucide-react

The range is wide, >=0.500.0 <2.0.0, so your app picks the version — both the 0.x and 1.x lines satisfy it. If a lucide release changes a drawing you care about, replace that one icon (step 5) rather than pinning the whole library.

2. Rename what you imported from @raystack/apsara/icons

That path used to export raw in-house SVG components. It now exports the 31 icons Apsara's components draw, as replaceable icon components. Twelve of the old names are gone.

Two names survive, both with a new drawing:

• CoPilotIcon: lucide Sparkles in place of the in-house solid sparkle.
• FilterIcon: lucide ListFilter in place of the in-house solid funnel.

A raw lucide component draws 24×24 at strokeWidth={2}, so set size={16} strokeWidth={1.5} at the call site to match the Apsara icons beside it, or wrap it once with createIcon, which applies those for you:

1// src/icons.ts
2import { createIcon } from '@raystack/apsara/icons';
3import { Bell } from 'lucide-react';
4
5export const BellIcon = createIcon('BellIcon', Bell);

See Building your own icons.

3. Check the icons that changed shape

These are inside Apsara's own components, so they change without you touching a call site. Everything else is the same glyph in a different drawing style.

Two more are worth a look, though the glyph is nearly the same:

• DatePicker and RangePicker draw CalendarIcon, which is lucide CalendarDays, so the glyph has day marks inside it.
• Search's clear button and Toast's error status draw CircleX in place of radix CrossCircledIcon.

4. Expect a 1px size change in some places

Every Apsara icon renders at 16×16 with strokeWidth={1.5}, which draws the 1px stroke of the design because lucide's viewBox is 24 units wide. The radix icons were intrinsically 15×15.

• A call site that set no size grows from 15px to 16px.
• A call site that set a CSS class is unaffected, since CSS beats an SVG presentation attribute.
• A call site that set width/height explicitly is unaffected, since your props are applied after Apsara's base values.

To change the size or the stroke of every icon at once, use the props half of <Theme icons>:

1<Theme icons={{ props: { width: 20, height: 20, strokeWidth: 1.25 } }}>

5. If you want the radix appearance back

Apsara ships no radix preset, so register the radix icons yourself at <Theme>. Keep @radix-ui/react-icons in your own dependencies and copy this map:

1'use client';
2
3import {
4  ArrowDownIcon,
5  ArrowUpIcon,
6  CalendarIcon,
7  CheckCircledIcon,
8  CheckIcon,
9  ChevronDownIcon,
10  ChevronLeftIcon,
11  ChevronRightIcon,
12  CopyIcon,
13  Cross1Icon,
14  CrossCircledIcon,
15  DotsHorizontalIcon,
16  ExclamationTriangleIcon,
17  FileTextIcon,
18  InfoCircledIcon,
19  MagnifyingGlassIcon,
20  MinusIcon,
21  MixerHorizontalIcon,
22  MoonIcon,
23  PlusIcon,
24  SizeIcon,
25  StopIcon,
26  SunIcon,
27  TableIcon,
28  TextAlignBottomIcon,
29  TextAlignTopIcon
30} from '@radix-ui/react-icons';
31import { Theme, type IconOverrides } from '@raystack/apsara';
32
33const radixIcons: IconOverrides = {
34  ArrowDownIcon: ArrowDownIcon,
35  ArrowUpIcon: ArrowUpIcon,
36  CalendarIcon: CalendarIcon,
37  CheckIcon: CheckIcon,
38  ChevronDownIcon: ChevronDownIcon,
39  ChevronLeftIcon: ChevronLeftIcon,
40  ChevronRightIcon: ChevronRightIcon,
41  ClearIcon: CrossCircledIcon,
42  CopyIcon: CopyIcon,
43  DisplayIcon: MixerHorizontalIcon,
44  EllipsisIcon: DotsHorizontalIcon,
45  ErrorIcon: CrossCircledIcon,
46  ExpandIcon: SizeIcon,
47  FileTextIcon: FileTextIcon,
48  InfoIcon: InfoCircledIcon,
49  MinusIcon: MinusIcon,
50  MoonIcon: MoonIcon,
51  PlusIcon: PlusIcon,
52  SearchIcon: MagnifyingGlassIcon,
53  ShrinkIcon: MinusIcon,
54  SortAscendingIcon: TextAlignTopIcon,
55  SortDescendingIcon: TextAlignBottomIcon,
56  StopIcon: StopIcon,
57  SuccessIcon: CheckCircledIcon,
58  SunIcon: SunIcon,
59  TableIcon: TableIcon,
60  WarningIcon: ExclamationTriangleIcon,
61  XIcon: Cross1Icon
62};
63
64export function Providers({ children }: { children: React.ReactNode }) {
65  return <Theme icons={{ components: radixIcons }}>{children}</Theme>;
66}

Three keys are not in the map, because radix has no equivalent: FilterIcon, PanelLeftIcon and CoPilotIcon. All three were in-house SVGs before. Radix MagicWandIcon is the nearest stand-in for CoPilotIcon if you want one.

You do not have to take the whole map. A partial map changes only the keys it names.

6. Register from a client component

An override map is an object of functions, and a function cannot cross the boundary from a React Server Component to a Client Component. If your <Theme> sits directly in a server layout today, move it into a providers.tsx file marked 'use client', as shown above.

This applies to any runtime icon override.

See Icons for the full set, the override API, and what each key draws.

1.0: Base UI replaces Radix and Ariakit

Apsara 1.0 rebuilds every component on Base UI in place of Radix UI, Ariakit, sonner and cmdk. It is the largest migration Apsara has had, and it has a dedicated guide: the v1 migration guide walks through every component with before-and-after examples. The headlines:

• React 19 is required. The peer range narrows from ^18 || ^19 to ^19.
• asChild becomes render. The Radix composition pattern is gone across every trigger and primitive; children move onto the wrapper.
• Callbacks gain a second argument. onValueChange, onOpenChange and onCheckedChange now receive an eventDetails object after the value.
• Data attributes and CSS variables change. data-state="open" becomes data-open, and the --radix-* variables become Base UI names such as --anchor-width. Custom CSS that targets Apsara internals needs updating.
• Form controls compose with Field. InputField becomes Input, and labels, descriptions and errors move to the new Field wrapper.
• Components are renamed. DropdownMenu becomes Menu and Sheet becomes Drawer, each with prop renames of its own.
• The pickers change contract. DatePicker and RangePicker gain slotProps, start unselected instead of defaulting to today, and require a real Date (or undefined) as value.
• Layout scales go numeric. Flex and Grid take gap={1} through gap={17} in place of the named sizes, and Headline sizes become t1–t4.

If you are coming from 0.x, work through the full guide in order: the cross-cutting changes first, then your components one by one.