Skip to content

Commit 0efb999

Browse files
theoribbitheoribbi
committed
chore: update package versions and release notes for primitives
1 parent dd7f5ed commit 0efb999

File tree

2 files changed

+742
-0
lines changed

2 files changed

+742
-0
lines changed

‎apps/website/docs/button.mdx‎

Lines changed: 378 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,378 @@
1+
---
2+
title: "Button"
3+
description: "Cross-platform button primitive that wraps React Native's Pressable. Provides a consistent API for interactive buttons across iOS, Android, and Web."
4+
---
5+
6+
---
7+
8+
## Preview
9+
10+
<Preview component="button" title="Interactive Demo" />
11+
12+
---
13+
14+
## Installation
15+
16+
<InstallTabs />
17+
18+
---
19+
20+
## Overview
21+
22+
Button is a cross-platform button primitive that provides a consistent API for interactive elements across iOS, Android, and Web. It's designed to be the foundation for building any type of button or pressable element.
23+
24+
| Feature | Description | Platforms |
25+
| ------------ | ------------------------------------------ | ----------------- |
26+
| **Button** | Standard pressable button with all Pressable props | iOS, Android, Web |
27+
| **asChild** | Polymorphic rendering for any component | iOS, Android, Web |
28+
| **Accessibility** | Proper ARIA attributes and roles | Web |
29+
| **Composable** | Use with any component via `asChild` | iOS, Android, Web |
30+
31+
---
32+
33+
## Setup & Usage Guide
34+
35+
Button works out of the box with no configuration. It's a drop-in replacement for React Native's `Pressable` with enhanced web semantics.
36+
37+
### 1. Install and Import
38+
39+
Install from npm:
40+
41+
```bash
42+
npm install @native-ui-org/primitives
43+
```
44+
45+
Then import from the package:
46+
47+
```tsx
48+
import { Button } from "@native-ui-org/primitives";
49+
```
50+
51+
---
52+
53+
### 2. Basic Usage
54+
55+
Use Button just like React Native's `Pressable`:
56+
57+
```tsx
58+
import { Button, Text } from "@native-ui-org/primitives";
59+
60+
function MyComponent() {
61+
return (
62+
<Button onPress={() => console.log("Pressed!")}>
63+
<Text>Click me</Text>
64+
</Button>
65+
);
66+
}
67+
```
68+
69+
---
70+
71+
### 3. With Styling
72+
73+
Apply styles directly to the Button:
74+
75+
```tsx
76+
<Button
77+
onPress={handlePress}
78+
style={{
79+
backgroundColor: "#007AFF",
80+
paddingHorizontal: 20,
81+
paddingVertical: 12,
82+
borderRadius: 8,
83+
}}
84+
>
85+
<Text style={{ color: "white", fontWeight: "600" }}>
86+
Submit
87+
</Text>
88+
</Button>
89+
```
90+
91+
---
92+
93+
### 4. Disabled State
94+
95+
Disable the button when needed:
96+
97+
```tsx
98+
<Button
99+
onPress={handlePress}
100+
disabled={isLoading}
101+
style={{
102+
opacity: isLoading ? 0.5 : 1,
103+
}}
104+
>
105+
<Text>Submit</Text>
106+
</Button>
107+
```
108+
109+
---
110+
111+
### 5. Press States
112+
113+
Handle different press states:
114+
115+
```tsx
116+
<Button
117+
onPress={handlePress}
118+
onPressIn={() => console.log("Pressing...")}
119+
onPressOut={() => console.log("Released")}
120+
onLongPress={() => console.log("Long press!")}
121+
>
122+
<Text>Press me</Text>
123+
</Button>
124+
```
125+
126+
---
127+
128+
### 6. Polymorphic Components with asChild
129+
130+
Use `asChild` to render any component as a button without an extra wrapper:
131+
132+
```tsx
133+
import { Button, View, Text } from "@native-ui-org/primitives";
134+
135+
// Render a View as a button
136+
<Button asChild onPress={handlePress}>
137+
<View style={{ backgroundColor: "blue", padding: 16 }}>
138+
<Text style={{ color: "white" }}>Custom Button</Text>
139+
</View>
140+
</Button>
141+
```
142+
143+
---
144+
145+
### 7. Composing with Other Components
146+
147+
Use `asChild` to compose Button with other primitives:
148+
149+
```tsx
150+
import { Button, Checkbox, View } from "@native-ui-org/primitives";
151+
152+
// Make a Checkbox pressable via Button
153+
<Button asChild onPress={toggleCheckbox}>
154+
<View>
155+
<Checkbox checked={isChecked} />
156+
</View>
157+
</Button>
158+
```
159+
160+
---
161+
162+
### 8. Web Semantic Elements
163+
164+
On web, use `asChild` to render semantic HTML elements:
165+
166+
```tsx
167+
// Render as a native <button> element
168+
<Button asChild onPress={handleSubmit}>
169+
<button type="submit">
170+
Submit Form
171+
</button>
172+
</Button>
173+
174+
// Render as an anchor tag
175+
<Button asChild onPress={handleNavigation}>
176+
<a href="/about">About</a>
177+
</Button>
178+
```
179+
180+
---
181+
182+
### 9. Accessibility
183+
184+
Button automatically includes proper accessibility attributes:
185+
186+
```tsx
187+
<Button
188+
onPress={handlePress}
189+
accessibilityLabel="Submit form"
190+
accessibilityHint="Submits the current form"
191+
accessibilityRole="button"
192+
>
193+
<Text>Submit</Text>
194+
</Button>
195+
```
196+
197+
---
198+
199+
## API Reference
200+
201+
### Button
202+
203+
The base button component for all platforms.
204+
205+
| Prop | Type | Default | Description |
206+
| --------------- | ------------------------- | ------- | ---------------------------------------------- |
207+
| `asChild` | boolean | `false` | Render child element without Button wrapper |
208+
| `onPress` | `(event: PressEvent) => void` | — | Callback when button is pressed |
209+
| `onPressIn` | `(event: PressEvent) => void` | — | Callback when press starts |
210+
| `onPressOut` | `(event: PressEvent) => void` | — | Callback when press ends |
211+
| `onLongPress` | `(event: PressEvent) => void` | — | Callback for long press |
212+
| `disabled` | boolean | `false` | Whether the button is disabled |
213+
| `accessibilityRole` | `"button"` | `"button"` | Accessibility role (defaults to "button") |
214+
| `accessibilityLabel` | string | — | Accessibility label for screen readers |
215+
| `accessibilityHint` | string | — | Accessibility hint for screen readers |
216+
| `accessibilityState` | `AccessibilityState` | — | Accessibility state (disabled, selected, etc.) |
217+
| `...props` | `PressableProps` | — | All React Native Pressable props |
218+
219+
---
220+
221+
## Platform Behavior
222+
223+
| Platform | Implementation | Characteristics |
224+
| --------------------- | ------------------------------------------- | --------------------------------- |
225+
| **iOS / Android** | Standard React Native `Pressable` | Native touch handling and feedback |
226+
| **Web** | Renders with `role="button"` | Proper semantic HTML and keyboard support |
227+
| **All Platforms** | Consistent API | Same props, same behavior |
228+
229+
---
230+
231+
## Accessibility
232+
233+
**Web:**
234+
235+
* Automatic `role="button"` attribute
236+
* Keyboard navigation support (Enter/Space)
237+
* Proper focus management
238+
* ARIA attributes support
239+
240+
**Mobile:**
241+
242+
* Standard React Native accessibility props
243+
* Works with VoiceOver and TalkBack
244+
* Proper accessibility roles and states
245+
246+
---
247+
248+
## Examples
249+
250+
### Form Submit Button
251+
252+
```tsx
253+
import { Button, Text } from "@native-ui-org/primitives";
254+
255+
function Form() {
256+
const handleSubmit = () => {
257+
// Handle form submission
258+
};
259+
260+
return (
261+
<Button
262+
onPress={handleSubmit}
263+
style={{
264+
backgroundColor: "#007AFF",
265+
paddingHorizontal: 24,
266+
paddingVertical: 12,
267+
borderRadius: 8,
268+
}}
269+
>
270+
<Text style={{ color: "white", fontWeight: "600" }}>
271+
Submit
272+
</Text>
273+
</Button>
274+
);
275+
}
276+
```
277+
278+
### Icon Button
279+
280+
```tsx
281+
import { Button, View } from "@native-ui-org/primitives";
282+
283+
function IconButton() {
284+
return (
285+
<Button
286+
onPress={handlePress}
287+
style={{
288+
width: 40,
289+
height: 40,
290+
borderRadius: 20,
291+
backgroundColor: "#F0F0F0",
292+
alignItems: "center",
293+
justifyContent: "center",
294+
}}
295+
>
296+
<View>
297+
{/* Your icon component here */}
298+
</View>
299+
</Button>
300+
);
301+
}
302+
```
303+
304+
### Loading State
305+
306+
```tsx
307+
import { Button, Text, ActivityIndicator } from "@native-ui-org/primitives";
308+
309+
function LoadingButton() {
310+
const [isLoading, setIsLoading] = useState(false);
311+
312+
return (
313+
<Button
314+
onPress={async () => {
315+
setIsLoading(true);
316+
await doSomething();
317+
setIsLoading(false);
318+
}}
319+
disabled={isLoading}
320+
style={{
321+
opacity: isLoading ? 0.6 : 1,
322+
}}
323+
>
324+
{isLoading ? (
325+
<ActivityIndicator color="white" />
326+
) : (
327+
<Text>Submit</Text>
328+
)}
329+
</Button>
330+
);
331+
}
332+
```
333+
334+
### Custom Button with asChild
335+
336+
```tsx
337+
import { Button, View, Text } from "@native-ui-org/primitives";
338+
339+
function CustomButton() {
340+
return (
341+
<Button asChild onPress={handlePress}>
342+
<View
343+
style={{
344+
flexDirection: "row",
345+
alignItems: "center",
346+
backgroundColor: "#007AFF",
347+
paddingHorizontal: 20,
348+
paddingVertical: 12,
349+
borderRadius: 8,
350+
gap: 8,
351+
}}
352+
>
353+
{/* Icon */}
354+
<View style={{ width: 20, height: 20, backgroundColor: "white" }} />
355+
<Text style={{ color: "white", fontWeight: "600" }}>
356+
Custom Button
357+
</Text>
358+
</View>
359+
</Button>
360+
);
361+
}
362+
```
363+
364+
---
365+
366+
## Version History
367+
368+
| Version | Notes |
369+
| ------- | ------------------------------------------------------------------------------- |
370+
| `0.9.0` | Initial release — cross-platform Button with `asChild` polymorphism and accessibility support. |
371+
372+
---
373+
374+
**Summary:**
375+
Button is the foundation for all interactive pressable elements in cross-platform apps.
376+
Use it everywhere you'd use React Native's Pressable, with the added benefit of better web semantics and composability through `asChild`.
377+
378+

0 commit comments

Comments
 (0)