Modal

Highlight key information or actions with a window that overlays content for focused interaction.

Installation

API Reference

Important Note

This is the documentation for gluestack-ui v2 (beta). For @gluestack-ui/themed (stable) documentation, refer to gluestack-ui v1.

This is an illustration of Modal component.

size

function App() {
  const [showModal, setShowModal] = React.useState(false)
  const ref = React.useRef(null)
  return (
    <Center className="h-[300px]">
      <Button onPress={() => setShowModal(true)} ref={ref}>
        <ButtonText>Show Modal</ButtonText>
      </Button>
      <Modal
        isOpen={showModal}
        onClose={() => {
          setShowModal(false)
        }}
        finalFocusRef={ref}
        size="md"
      >
        <ModalBackdrop />
        <ModalContent>
          <ModalHeader>
            <Heading size="md" className="text-typography-950">
              Invite your team
            </Heading>
            <ModalCloseButton>
              <Icon
                as={CloseIcon}
                size="md"
                className="stroke-background-400 group-[:hover]/modal-close-button:stroke-background-700 group-[:active]/modal-close-button:stroke-background-900 group-[:focus-visible]/modal-close-button:stroke-background-900"
              />
            </ModalCloseButton>
          </ModalHeader>
          <ModalBody>
            <Text size="sm" className="text-typography-500">
              Elevate user interactions with our versatile modals. Seamlessly
              integrate notifications, forms, and media displays. Make an impact
              effortlessly.
            </Text>
          </ModalBody>
          <ModalFooter>
            <Button
              variant="outline"
              action="secondary"
              onPress={() => {
                setShowModal(false)
              }}
            >
              <ButtonText>Cancel</ButtonText>
            </Button>
            <Button
              onPress={() => {
                setShowModal(false)
              }}
            >
              <ButtonText>Explore</ButtonText>
            </Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </Center>
  )
}

Installation

CLI

Manual

Run the following command:

npx gluestack-ui add modal

Step 1: Install the following dependencies:

npm i @gluestack-ui/modal @legendapp/motion

Important Note

Note: At present, we have integrated the @legendapp/motion for animation. You have the option to remove this and implement your own custom animation wrapper.

Step 2: Copy and paste the following code into your project.

"use client"
import React from "react"
import { createModal } from "@gluestack-ui/modal"
import { Pressable, View, ScrollView, Platform } from "react-native"
import {
  Motion,
  AnimatePresence,
  createMotionAnimatedComponent,
} from "@legendapp/motion"
import { tva } from "@gluestack-ui/nativewind-utils/tva"
import {
  withStyleContext,
  useStyleContext,
} from "@gluestack-ui/nativewind-utils/withStyleContext"
import { withStyleContextAndStates } from "@gluestack-ui/nativewind-utils/withStyleContextAndStates"
import { cssInterop } from "nativewind"
import type { VariantProps } from "@gluestack-ui/nativewind-utils"

const AnimatedPressable = createMotionAnimatedComponent(Pressable)

const SCOPE = "MODAL"

const UIModal = createModal({
  Root:
    Platform.OS === "web"
      ? withStyleContext(View, SCOPE)
      : withStyleContextAndStates(View, SCOPE),
  Backdrop: AnimatedPressable,
  Content: Motion.View,
  Body: ScrollView,
  CloseButton: Pressable,
  Footer: View,
  Header: View,
  AnimatePresence: AnimatePresence,
})
cssInterop(UIModal, { className: "style" })
cssInterop(UIModal.Backdrop, { className: "style" })
cssInterop(UIModal.Content, { className: "style" })
cssInterop(UIModal.CloseButton, { className: "style" })
cssInterop(UIModal.Header, { className: "style" })
cssInterop(UIModal.Body, {
  className: "style",
  contentContainerClassName: "contentContainerStyle",
  indicatorClassName: "indicatorStyle",
})
cssInterop(UIModal.Footer, { className: "style" })

const modalStyle = tva({
  base: "group/modal w-full h-full justify-center items-center web:pointer-events-none",
  variants: {
    size: {
      xs: "",
      sm: "",
      md: "",
      lg: "",
      full: "",
    },
  },
})

const modalBackdropStyle = tva({
  base: "absolute left-0 top-0 right-0 bottom-0 bg-background-dark web:cursor-default",
})

const modalContentStyle = tva({
  base: "bg-background-0 rounded-md overflow-hidden border border-outline-100 shadow-hard-2 p-6",
  parentVariants: {
    size: {
      xs: "w-[60%] max-w-[360px]",
      sm: "w-[70%] max-w-[420px]",
      md: "w-[80%] max-w-[510px]",
      lg: "w-[90%] max-w-[640px]",
      full: "w-full",
    },
  },
})

const modalBodyStyle = tva({
  base: "mt-4 mb-6",
})

const modalCloseButtonStyle = tva({
  base: "group/modal-close-button z-10 rounded data-[focus-visible=true]:web:bg-background-100 web:outline-0 cursor-pointer",
})

const modalHeaderStyle = tva({
  base: "justify-between items-center flex-row",
})

const modalFooterStyle = tva({
  base: "flex-row justify-end items-center gap-2",
})

type IModalProps = React.ComponentProps<typeof UIModal> &
  VariantProps<typeof modalStyle>

type IModalBackdropProps = React.ComponentProps<typeof UIModal.Backdrop> &
  VariantProps<typeof modalBackdropStyle>

type IModalContentProps = React.ComponentProps<typeof UIModal.Content> &
  VariantProps<typeof modalContentStyle>

type IModalHeaderProps = React.ComponentProps<typeof UIModal.Header> &
  VariantProps<typeof modalHeaderStyle>

type IModalBodyProps = React.ComponentProps<typeof UIModal.Body> &
  VariantProps<typeof modalBodyStyle>

type IModalFooterProps = React.ComponentProps<typeof UIModal.Footer> &
  VariantProps<typeof modalFooterStyle>

type IModalCloseButtonProps = React.ComponentProps<typeof UIModal.CloseButton> &
  VariantProps<typeof modalCloseButtonStyle>

const Modal = React.forwardRef(
  (
    //@ts-ignore
    { className, size = "md", ...props }: { className?: string } & IModalProps,
    ref?: any
  ) => (
    <UIModal
      ref={ref}
      {...props}
      pointerEvents="box-none"
      className={modalStyle({ size, class: className })}
      context={{ size }}
    />
  )
)

const ModalBackdrop = React.forwardRef(
  (
    { className, ...props }: { className?: string } & IModalBackdropProps,
    ref?: any
  ) => {
    return (
      <UIModal.Backdrop
        ref={ref}
        initial={{
          opacity: 0,
        }}
        animate={{
          opacity: 0.5,
        }}
        exit={{
          opacity: 0,
        }}
        transition={{
          type: "spring",
          damping: 18,
          stiffness: 250,
          opacity: {
            type: "timing",
            duration: 250,
          },
        }}
        {...props}
        className={modalBackdropStyle({
          class: className,
        })}
      />
    )
  }
)

const ModalContent = React.forwardRef(
  (
    { className, size, ...props }: { className?: string } & IModalContentProps,
    ref?: any
  ) => {
    const { size: parentSize } = useStyleContext(SCOPE)

    return (
      <UIModal.Content
        ref={ref}
        initial={{
          opacity: 0,
          scale: 0.9,
        }}
        animate={{
          opacity: 1,
          scale: 1,
        }}
        exit={{
          opacity: 0,
        }}
        transition={{
          type: "spring",
          damping: 18,
          stiffness: 250,
          opacity: {
            type: "timing",
            duration: 250,
          },
        }}
        {...props}
        className={modalContentStyle({
          parentVariants: {
            size: parentSize,
          },
          size,
          class: className,
        })}
        pointerEvents="auto"
      />
    )
  }
)

const ModalHeader = React.forwardRef(
  (
    { className, ...props }: { className?: string } & IModalHeaderProps,
    ref?: any
  ) => (
    <UIModal.Header
      ref={ref}
      {...props}
      className={modalHeaderStyle({
        class: className,
      })}
    />
  )
)

const ModalBody = React.forwardRef(
  (
    { className, ...props }: { className?: string } & IModalBodyProps,
    ref?: any
  ) => (
    <UIModal.Body
      ref={ref}
      {...props}
      className={modalBodyStyle({
        class: className,
      })}
    />
  )
)

const ModalFooter = React.forwardRef(
  (
    { className, ...props }: { className?: string } & IModalFooterProps,
    ref?: any
  ) => (
    <UIModal.Footer
      ref={ref}
      {...props}
      className={modalFooterStyle({
        class: className,
      })}
    />
  )
)

const ModalCloseButton = React.forwardRef(
  (
    { className, ...props }: { className?: string } & IModalCloseButtonProps,
    ref?: any
  ) => (
    <UIModal.CloseButton
      ref={ref}
      {...props}
      className={modalCloseButtonStyle({
        class: className,
      })}
    />
  )
)

// Assign display names
Modal.displayName = "Modal"
ModalBackdrop.displayName = "ModalBackdrop"
ModalContent.displayName = "ModalContent"
ModalHeader.displayName = "ModalHeader"
ModalBody.displayName = "ModalBody"
ModalFooter.displayName = "ModalFooter"
ModalCloseButton.displayName = "ModalCloseButton"

export {
  Modal,
  ModalBackdrop,
  ModalContent,
  ModalCloseButton,
  ModalHeader,
  ModalBody,
  ModalFooter,
}

Step 3: Update the import paths to match your project setup.

API Reference

To use this component in your project, include the following import statement in your file.

import { Modal } from "@/components/ui/modal"

export default () => (
  <Modal>
    <ModalBackdrop />
    <ModalContent>
      <ModalHeader>
        <ModalCloseButton></ModalCloseButton>
      </ModalHeader>
      <ModalBody />
      <ModalFooter />
    </ModalContent>
  </Modal>
)

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

Contains all View related layout style props and actions. It inherits all the properties of React Native's View component.

Prop	Type	Default	Description
isOpen	boolean	-	If true, the modal will open. Useful for controllable state behavior.
onClose	() => any	-	Callback invoked when the modal is closed.
useRNModal	boolean	false	If true, renders react-native native modal.
defaultIsOpen	boolean	-	Specifies the default open state of the Modal
initialFocusRef	React.RefObject<any>	-	The ref of element to receive focus when the modal opens.
finalFocusRef	React.RefObject<any>	-	The ref of element to receive focus when the modal closes
avoidKeyboard	boolean	-	If true, the Modal will avoid the keyboard.
closeOnOverlayClick	boolean	-	If true, the Modal will close when the overlay is clicked.
isKeyboardDismissable	boolean	-	If true, the keyboard can dismiss the Modal
children	any	-	The content to display inside the Modal

ModalBackdrop

It is React Native's Pressable component, created using @legendapp/motion's createMotionAnimatedComponent function to add animation to the component. You can use any declarative animation library you prefer.

ModalContent

It is @legendapp/motion's Motion.View component. You can use any declarative animation library you prefer.

Prop	Type	Default	Description
focusable	boolean	false	If true, Modal Content will be focusable.

ModalHeader

It inherits all the properties of React Native's View component.

ModalCloseButton

It inherits all the properties of React Native's View component.

ModalBody

It inherits all the properties of React Native's View component

ModalFooter

It inherits all the properties of React Native's View component.

Accessibility

We have outlined the various features that ensure the Modal component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards. It uses React Native ARIA @react-native-aria/focus which follows the Dialog Modal WAI-ARIA design pattern.

Props

Modal component is created using View component from react-native. It extends all the props supported by React Native View, utility props and the props mentioned below.

Name	Value	Default
size	xs \| sm \| md \| lg \| full	md

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Multiple Modals

A user interface featuring multiple modal components that allow for layered interaction and context-specific information display.

function App() {
  const [showModal, setShowModal] = React.useState(false)
  const [showModal2, setShowModal2] = React.useState(false)
  const [showModal3, setShowModal3] = React.useState(false)
  return (
    <>
      <Button onPress={() => setShowModal(true)}>
        <ButtonText>Forgot password?</ButtonText>
      </Button>
      <Modal
        isOpen={showModal}
        onClose={() => {
          setShowModal(false)
        }}
      >
        <ModalBackdrop />
        <ModalContent>
          <ModalHeader className="flex-col items-start gap-0.5">
            <Heading>Forgot password?</Heading>
            <Text size="sm">No worries, we’ll send you reset instructions</Text>
          </ModalHeader>
          <ModalBody className="mb-4">
            <Input>
              <InputField placeholder="Enter your email" />
            </Input>
          </ModalBody>
          <ModalFooter className="flex-col items-start">
            <Button
              onPress={() => {
                setShowModal2(true)
              }}
              className="w-full"
            >
              <ButtonText>Submit</ButtonText>
            </Button>
            <Button
              variant="link"
              size="sm"
              onPress={() => {
                setShowModal(false)
              }}
              className="gap-1"
            >
              <ButtonIcon as={ArrowLeftIcon} />
              <ButtonText>Back to login</ButtonText>
            </Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
      <Modal
        isOpen={showModal2}
        onClose={() => {
          setShowModal2(false)
        }}
      >
        <ModalBackdrop />
        <ModalContent>
          <ModalHeader className="flex-col items-start gap-0.5">
            <Heading>Reset password</Heading>
            <Text size="sm">
              A verification code has been sent to you. Enter code below.
            </Text>
          </ModalHeader>
          <ModalBody className="mb-4">
            <Input>
              <InputField placeholder="Enter verification code" />
            </Input>
          </ModalBody>
          <ModalFooter className="flex-col items-start">
            <Button
              onPress={() => {
                setShowModal3(true)
              }}
              className="w-full"
            >
              <ButtonText>Continue</ButtonText>
            </Button>
            <Text size="sm" className="">
              Didn’t receive the email?
              <Link className="">
                <LinkText
                  size="xs"
                  className="text-typography-700 font-semibold"
                >
                  Click to resend
                </LinkText>
              </Link>
            </Text>
            <HStack space="xs" className="items-center">
              <Button
                variant="link"
                size="sm"
                onPress={() => {
                  setShowModal2(false)
                }}
                className="gap-1"
              >
                <ButtonIcon as={ArrowLeftIcon} />
                <ButtonText>Back to login</ButtonText>
              </Button>
            </HStack>
          </ModalFooter>
        </ModalContent>
      </Modal>
      <Modal
        isOpen={showModal3}
        onClose={() => {
          setShowModal3(false)
        }}
      >
        <ModalBackdrop />
        <ModalContent>
          <ModalHeader className="flex-col items-start gap-0.5">
            <Heading>Set new password</Heading>
            <Text size="sm">
              Almost done. Enter your new password and you are all set.
            </Text>
          </ModalHeader>
          <ModalBody className="" contentContainerClassName="gap-3">
            <Input>
              <InputField placeholder="New password" />
            </Input>
            <Input>
              <InputField placeholder="Confirm new password" />
            </Input>
          </ModalBody>
          <ModalFooter className="flex-col items-start">
            <Button
              onPress={() => {
                setShowModal(false)
                setShowModal2(false)
                setShowModal3(false)
              }}
              className="w-full"
            >
              <ButtonText>Submit</ButtonText>
            </Button>
            <Button
              variant="link"
              size="sm"
              onPress={() => {
                setShowModal3(false)
              }}
              className="gap-1"
            >
              <ButtonIcon as={ArrowLeftIcon} />
              <ButtonText>Back to login</ButtonText>
            </Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  )
}

Onboarding Message

function App() {
  const [showModal, setShowModal] = React.useState(false)
  return (
    <>
      <Button onPress={() => setShowModal(true)}>
        <ButtonText>Dashboard</ButtonText>
      </Button>
      <Modal
        isOpen={showModal}
        onClose={() => {
          setShowModal(false)
        }}
      >
        <ModalBackdrop />
        <ModalContent className="max-w-[375px]">
          <Image
            source={{
              uri: "https://s3-alpha-sig.figma.com/img/699b/4163/a76185f77e8785f5dd5b8ab61c92aa5c?Expires=1722211200&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=prgL91-UWtjpEALlOeixZRZA-J6IQ0ltBJBsVxMCLLckr6q~nS39Q3afbbUZVMU53bae2kwUzxLqrowQEkSFgqjHofoZeayW4B0HYFzxFXwep20vUtGUdGQRM5KINMBKVSht2vA1qIAz8uo26q7ECgDPDImgUa4GNBByKDsErzMwU7RoUz-v2EkM238BToy8wyWDPeJG3eqydV9dQuL7ExJLlYBIBO0hqouyVrPp9dclvm6K~bhZiehddcR7DW~~57~~4F7g~osk0SFtqRIIlS-smuRlxPKigT4Gds8D8T2uC-VSyCgJ7ZEqtb~MT2jpeUAjVWXjT5vzAQg-dFdSUw__",
            }}
            alt="image"
            className="h-[185px] w-full rounded"
          />
          <ModalBody className="mb-5" contentContainerClassName="">
            <Heading size="md" className="text-typography-950 text-center">
              Welcome to the dashboard
            </Heading>
            <Text size="sm" className="text-typography-500 text-center">
              We are glad to have you on board, Here are some quick tips to let
              you up and running.
            </Text>
          </ModalBody>
          <ModalFooter className="w-full">
            <Button
              variant="outline"
              action="secondary"
              size="sm"
              onPress={() => {
                setShowModal(false)
              }}
              className="flex-grow"
            >
              <ButtonText>Skip</ButtonText>
            </Button>
            <Button
              onPress={() => {
                setShowModal(false)
              }}
              size="sm"
              className="flex-grow"
            >
              <ButtonText>Next</ButtonText>
            </Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  )
}

Delete Post

function App() {
  const [showModal, setShowModal] = React.useState(false)
  return (
    <>
      <Button onPress={() => setShowModal(true)}>
        <ButtonText>Delete Post</ButtonText>
      </Button>
      <Modal
        isOpen={showModal}
        onClose={() => {
          setShowModal(false)
        }}
      >
        <ModalBackdrop />
        <ModalContent className="max-w-[305px] items-center">
          <ModalHeader>
            <Box className="w-[56px] h-[56px] rounded-full bg-background-error items-center justify-center">
              <Icon as={TrashIcon} className="stroke-error-600" size="xl" />
            </Box>
          </ModalHeader>
          <ModalBody className="mt-0 mb-4">
            <Heading size="md" className="text-typography-950 mb-2 text-center">
              Delete blog post
            </Heading>
            <Text size="sm" className="text-typography-500 text-center">
              Are you sure you want to delete this post? This action cannot be
              undone.
            </Text>
          </ModalBody>
          <ModalFooter className="w-full">
            <Button
              variant="outline"
              action="secondary"
              size="sm"
              onPress={() => {
                setShowModal(false)
              }}
              className="flex-grow"
            >
              <ButtonText>Cancel</ButtonText>
            </Button>
            <Button
              onPress={() => {
                setShowModal(false)
              }}
              size="sm"
              className="flex-grow"
            >
              <ButtonText>Delete</ButtonText>
            </Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  )
}

Invite Friends to Project

function App() {
  const [showModal, setShowModal] = React.useState(false)
  return (
    <>
      <Button onPress={() => setShowModal(true)}>
        <ButtonText>Invite</ButtonText>
      </Button>
      <Modal
        isOpen={showModal}
        onClose={() => {
          setShowModal(false)
        }}
      >
        <ModalBackdrop />
        <ModalContent className="max-w-[395px]">
          <ModalHeader className="gap-2 items-start">
            <VStack className="gap-1">
              <Heading size="md" className="text-typography-950">
                Invite your team
              </Heading>
              <Text size="sm" className="text-typography-500">
                You have created a new project! Invite colleagues to collaborate
                on this project.
              </Text>
            </VStack>
            <ModalCloseButton>
              <Icon as={CloseIcon} className="stroke-background-500" />
            </ModalCloseButton>
          </ModalHeader>
          <ModalBody
            className="mb-0"
            contentContainerClassName="gap-4 space-between flex-row items-center"
          >
            <Input variant="outline" size="sm" className="flex-1">
              <InputField placeholder="join.untitledui.com/personalproject" />
            </Input>
            <Pressable className="h-9 w-9 justify-center items-center border border-outline-300 rounded">
              <Icon as={CopyIcon} className="stroke-background-800" />
            </Pressable>
          </ModalBody>
        </ModalContent>
      </Modal>
    </>
  )
}