# Designs: Patine and native

> Every Patine component ships in one refined design on iOS, Android and the web, with each platform's behaviour built in. Set design="native" for iOS on iPhone, Material Design on Android and a web design in the browser.

# Designs

Every component ships in the **Patine design**: one refined look, the same on iPhone, Android and the web. It's what this site, the screenshots and the Pro screens show, and you don't write anything for it.

Behaviour follows the platform whatever the design: fields open a bottom sheet on phones and a dropdown in the browser, sheets leave room for the home indicator, and the web gets keyboard, hover and focus. So the Patine design looks the same everywhere and still feels native.

If your app should look like each platform instead, set `design="native"`: **iOS** on iPhone and iPad, **Material Design** on Android, and a **web** design in the browser, from the same code.

```tsx
<PatineProvider design="native">
  <App />
</PatineProvider>
```

A design changes shapes and layout: where Cancel and Done sit, how a field and a chosen day look, whether time is picked on wheels, a clock dial or columns. It never changes your colors, fonts or anything you set yourself. Switch between the three native designs here:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import {
  DatePickerField,
  SegmentedControl,
  TimePicker,
} from 'patine-ui';
import type { Design } from 'patine-ui';

const DESIGNS = [
  { label: 'iOS', value: 'ios' },
  { label: 'Material', value: 'material' },
  { label: 'Web', value: 'web' },
] as const;

export default function Example() {
  const [design, setDesign] = useState<Design>('material');
  const [date, setDate] = useState<Date | null>(null);
  const [time, setTime] = useState(new Date());
  return (
    <View style={{ gap: 16 }}>
      <SegmentedControl
        items={DESIGNS}
        value={design}
        onValueChange={setDesign}
      />
      <DatePickerField
        design={design}
        label="Date"
        value={date}
        onConfirm={setDate}
      />
      <TimePicker
        design={design}
        value={time}
        onValueChange={setTime}
      />
    </View>
  );
}
```

## What each design changes

The three native designs side by side. The Patine design (`'brand'`) is closest to `web` in layout, with fields and rows sized for fingers (44pt) and its own radii and shadows.

| | `ios` | `material` | `web` |
| --- | --- | --- | --- |
| Fields | label above, 48 tall | outlined, 56 tall; the label sits inside, then floats onto the border | label above, 40 tall, focus ring while open |
| Sheet corners | 24 | 28 | 12 |
| Cancel / confirm | beside a centered title, **Done** | after the content, **OK** | after the content, **Done** |
| Single select | ✓ beside the chosen option | a radio on every option | ✓ beside the chosen option |
| Option rows | rounded and tinted when chosen | edge to edge, untinted | compact, rounded and tinted |
| Calendar | chosen day tinted, today's number coloured, SUN MON | chosen day filled, today ringed, S M T | chosen day a filled square, today shaded, Sun Mon |
| Date sheet | calendar | the picked date in large type above the calendar | calendar |
| Time | wheels | a clock dial | columns of hours and minutes to click |
| Date & time | one row of wheels | calendar with time fields to type into under it | calendar with the time columns beside it |
| Time range | **Start** and **End** rows, the wheels opening under the one you tap | two large time boxes with an arrow and the length, a clock dial for the chosen end | two cards side by side with an arrow and the length, columns for the chosen end |
| Duration | wheels with units | number boxes to type into | columns to click |
| Month | month and year wheels | a grid of months under the year | a grid of months under the year |
| WeekStrip | chosen day tinted, SUN MON | chosen day filled, S M T | chosen day a filled square, Sun Mon |
| Colour | Grid, Spectrum and Sliders tabs, swatches in a row to scroll | swatch circles, then **Custom** for a saturation square and hue slider | a saturation square, eyedropper, hue slider and hex code, then swatches |
| Slider | a white knob on a thin track | a slim handle with gaps on a thick track, stop dots, a value bubble while dragging | a solid dot on a medium track, a halo on hover and press |
| InputOTP | bordered boxes, the focused one in the primary colour | outlined boxes, the focused one with a 2dp primary outline | compact outlined boxes, the focused one with a focus ring |
| Rating | gold ★ stars | gold ★ stars | gold ★ stars; the pointer previews the rating a click would pick |
| DropdownMenu | 250 px wide, icons after the label, hairlines between actions, a small centered title | 200 px, icons first, 48 px rows | 200 px, icons first, compact 36 px rows |
| ActionSheet | centered actions in a floating rounded card, Cancel in its own card | rows on the sheet with icons, no Cancel | rows, a centered modal on wide windows, no Cancel |
| SegmentedControl, ChipGroup | a sliding raised thumb; filled chips | outlined segments and chips, the chosen one filled with a ✓ | a sliding raised thumb; filled chips |
| Search fields | a short gray search bar | a tall pill | an outlined input with a focus ring |
| EmojiPicker | categories at the bottom, the current one on a gray fill, UPPERCASE titles | categories at the bottom, the current one in a tinted pill | categories on top, underlined |
| Press | dims while held; buttons and chips shrink to 97% and spring back (brand too) | ripple from the touch point, no shrink | dims while held; buttons and chips shrink to 98% |

`CountryPicker` and `TimeZonePicker` are `Select`s and `PhoneField` is a field, so they follow the Fields, Single select and Option rows lines.

`design="native"` picks `ios` on iOS, `web` on the web, and `material` everywhere else (Android, Windows, macOS). The default, `design="brand"`, is the Patine design on every platform. Every component's `design` prop takes the same values, `'native'` included, and wins over the provider's: `<Select design="native" … />` draws the platform's own select inside a Patine-designed screen.

## One design everywhere

Set `design` on the provider to use one look on every platform. To keep the iOS look on Android and the web:

```tsx
<PatineProvider design="ios">
  <App />
</PatineProvider>
```

Or Material everywhere, for an app built on Material Design:

```tsx
<PatineProvider design="material">
  <App />
</PatineProvider>
```

## One component

`design` on a component wins over the provider's. A field passes its design to the sheet it opens.

```tsx
<Select design="material" options={options} value={value} onValueChange={setValue} />
<TimePickerField design="ios" label="Alarm" value={time} onConfirm={setTime} />
```

## Only part of a design

Some choices a design makes are props of their own, so you can keep the rest of a design and change just that:

| To get | Set |
| --- | --- |
| Wheels for time in any design | `display="wheel"` on `TimePicker` |
| A clock dial, typed fields or columns | `display="dial"`, `"input"` or `"list"` on `TimePicker` |
| One row of date and time wheels | `display="wheel"` on `DateTimePicker` |
| A calendar with time wheels | `display="calendar"` and `timeDisplay="wheel"` on `DateTimePicker` |
| The time beside or under the calendar | `timePosition="beside"` or `"below"` on `DateTimePicker` |
| `Mon` instead of `M` | `weekdayFormat="short"` on `DatePicker` |
| Your own button labels | `confirmLabel` / `cancelLabel` on any sheet or field |

## Customize a design

A design is a starting point. Everything you set wins over it:

- **Theme tokens.** `theme` and `darkTheme` on `PatineProvider` (colors, radius, spacing, fonts) are merged on top of the design's tokens. `radius.sheet` sets sheet corners in every design. See [Theming](./theming).
- **Slot styles.** Every visual part takes a style through `styles`. See [Styling with slots](./styling).
- **Render props.** Replace a row, a day, a trigger or a chevron and keep the behavior. See [Render props](./render-props).
- **Explicit props.** `confirmLabel`, `weekdayFormat`, `display` and the others above always win over the design's defaults.

`DESIGN_TOKENS` shows exactly what each design changes on the light or dark theme. In your own components, `useTheme().design` tells you which design to match:

```tsx
const theme = useTheme();
const radius = theme.design === 'material' ? theme.radius.full : theme.radius.md;
```

## Previewing other platforms

`design` sets the look. To also see how pickers *behave* on another platform in a browser (fields opening a bottom sheet instead of a dropdown, room for the iOS home indicator), set `platform` on the provider. See [Previewing other platforms](./platforms#previewing-other-platforms). On this site, the **Examples: Patine / Native** toggle at the top of each component page switches the look of every example, and the **Behaves like** iOS / Android / Web switch, on the examples whose behaviour changes by platform, switches the behaviour (and, with Native, the look).
