# Button **Category**: native **URL**: https://www.heroui.com/docs/native/components/button **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(buttons)/button.mdx > Interactive component that triggers an action when pressed. *** ## Import ```tsx import { Button } from 'heroui-native'; ``` ## Anatomy ```tsx ... ``` - **Button**: Main container that handles press interactions, animations, and variants. Renders string children as label or accepts compound components for custom layouts. - **Button.Label**: Text content of the button. Inherits size and variant styling from parent Button context. ## Usage ### Basic Usage The Button component accepts string children that automatically render as label. ```tsx Basic Button ``` ### With Compound Parts Use Button.Label for explicit control over the label component. ```tsx Click me ``` ### With Icons Combine icons with labels for enhanced visual communication. ```tsx Add Item Download ``` ### Icon Only Create square icon-only buttons using the isIconOnly prop. ```tsx ``` ### Sizes Control button dimensions with three size options. ```tsx Small Medium Large ``` ### Variants Choose from seven visual variants for different emphasis levels. ```tsx Primary Secondary Tertiary Outline Ghost Danger Danger Soft ``` ### Feedback Variants The `feedbackVariant` prop controls which press feedback effects are rendered: - `'scale-highlight'` (default): Built-in scale + highlight overlay - `'scale-ripple'`: Built-in scale + ripple overlay - `'scale'`: Built-in scale only (no overlay) - `'none'`: No feedback animations at all ```tsx {/* Scale + Highlight (default) */} Highlight Effect {/* Scale + Ripple */} Ripple Effect {/* Scale only */} Scale Only {/* No feedback */} No Feedback ``` ### Custom Animation The `animation` prop controls individual sub-animations. Its shape depends on the `feedbackVariant`. ```tsx {/* Customize scale and highlight (default feedbackVariant) */} Custom Highlight {/* Customize scale and ripple */} Custom Ripple ``` ### Disable Individual Animations Disable specific sub-animations by setting them to `false`: ```tsx {/* Disable scale, keep highlight */} No Scale {/* Disable highlight, keep scale */} No Highlight {/* Disable both */} No Animations ``` ### Disable All Animations Use `animation={false}` to disable all feedback, or `animation="disable-all"` for cascading disable: ```tsx Disabled Disable All (cascading) ``` ### Loading State with Spinner Transform button to loading state with spinner animation. ```tsx const themeColorAccentForeground = useThemeColor('accent-foreground'); { setIsDownloading(true); setTimeout(() => { setIsDownloading(false); }, 3000); }} isIconOnly={isDownloading} className="self-center" > {isDownloading ? ( ) : ( 'Download now' )} ; ``` ### Custom Background with LinearGradient Add gradient backgrounds using absolute positioned elements. Use `feedbackVariant="none"` to disable the default highlight overlay, or use `feedbackVariant="scale-ripple"` for a custom ripple effect. ```tsx import { Button, PressableFeedback } from 'heroui-native'; import { LinearGradient } from 'expo-linear-gradient'; import { StyleSheet } from 'react-native'; {/* Gradient with no feedback overlay */} Gradient {/* Gradient with custom ripple effect */} Gradient with Ripple ``` ## Example ```tsx import { Button, useThemeColor } from 'heroui-native'; import { Ionicons } from '@expo/vector-icons'; import { View } from 'react-native'; export default function ButtonExample() { const [ themeColorAccentForeground, themeColorAccentSoftForeground, themeColorDangerForeground, themeColorDefaultForeground, ] = useThemeColor([ 'accent-foreground', 'accent-soft-foreground', 'danger-foreground', 'default-foreground', ]); return ( Add Item Learn More ); } ``` You can find more examples in the [GitHub repository](). ## API Reference ### Button Button extends all props from [PressableFeedback](./pressable-feedback) (except `animation`, which is redefined) with additional button-specific props. | prop | type | default | description | | ----------------- | --------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------- | | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | `'primary'` | Visual variant of the button | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button | | `isIconOnly` | `boolean` | `false` | Whether the button displays an icon only (square aspect ratio) | | `feedbackVariant` | `'scale-highlight' \| 'scale-ripple' \| 'scale' \| 'none'` | `'scale-highlight'` | Determines which feedback effects are rendered | | `animation` | `ButtonAnimation` | - | Animation configuration (shape depends on `feedbackVariant`) | For inherited props including `isDisabled`, `className`, `children`, and all Pressable props, see [PressableFeedback API Reference](./pressable-feedback#api-reference). #### ButtonAnimation The `animation` prop is a discriminated union based on `feedbackVariant`. It follows the `AnimationRoot` control flow: - `true` or `undefined`: Use default animations - `false` or `"disabled"`: Disable all feedback animations - `"disable-all"`: Cascade-disable all animations including child compound parts - `object`: Custom configuration with sub-animation keys (see below) **When `feedbackVariant="scale-highlight"` (default):** | prop | type | default | description | | ----------- | ---------------------------------------- | ------- | ------------------------------------------------------------ | | `scale` | `PressableFeedbackScaleAnimation` | - | Scale animation config (`false` to disable) | | `highlight` | `PressableFeedbackHighlightAnimation` | - | Highlight overlay config (`false` to disable) | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Control animation state while keeping config (runtime toggle) | **When `feedbackVariant="scale-ripple"`:** | prop | type | default | description | | -------- | ---------------------------------------- | ------- | ------------------------------------------------------------ | | `scale` | `PressableFeedbackScaleAnimation` | - | Scale animation config (`false` to disable) | | `ripple` | `PressableFeedbackRippleAnimation` | - | Ripple overlay config (`false` to disable) | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Control animation state while keeping config (runtime toggle) | **When `feedbackVariant="scale"`:** | prop | type | default | description | | ------- | ---------------------------------------- | ------- | ------------------------------------------------------------ | | `scale` | `PressableFeedbackScaleAnimation` | - | Scale animation config (`false` to disable) | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Control animation state while keeping config (runtime toggle) | **When `feedbackVariant="none"`:** Only `'disable-all'` is accepted as a string value. All feedback effects are disabled. For detailed animation sub-types (`PressableFeedbackScaleAnimation`, `PressableFeedbackHighlightAnimation`, `PressableFeedbackRippleAnimation`), see [PressableFeedback API Reference](./pressable-feedback#api-reference). ### Button.Label | prop | type | default | description | | -------------- | ----------------- | ------- | ------------------------------------- | | `children` | `React.ReactNode` | - | Content to be rendered as label | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard Text props are supported | ## Hooks ### useButton Hook to access the Button context values. Returns the button's size, variant, and disabled state. ```tsx import { useButton } from 'heroui-native'; const { size, variant, isDisabled } = useButton(); ``` #### Return Value | property | type | description | | ------------ | --------------------------------------------------------------------------------------------- | ------------------------------ | | `size` | `'sm' \| 'md' \| 'lg'` | Size of the button | | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | Visual variant of the button | | `isDisabled` | `boolean` | Whether the button is disabled | **Note:** This hook must be used within a `Button` component. It will throw an error if called outside of the button context.