Test helper to apply pending React updates before making assertions.
Documentation

Reads the current Owner Stack in development and returns it as a string if available.

Owner Stacks are available in

• Component render
• Effects (e.g. use_effect)
• React’s event handlers (e.g. button([a.on_click(fn (_) {...})]))
• React error handlers (React Root options onCaughtError, onRecoverableError, and onUncaughtError)

If no Owner Stack is available, null is returned (see Troubleshooting: The Owner Stack is null).

Owner Stacks are only available in development. captureOwnerStack will always return null outside of development.

Documentation

Create a Redraw component, with a name, and a render function. render will accept props, and a list of children.

Create a Redraw component, with a name, and a render function. A render function is simply a function accepting props, and returning an Element.

pub fn my_component() {
  // Create your other Redraw components before defining the others.
  use my_other_component <- redraw.compose(my_other_component())
  // Define your component.
  use props: MyComponentProps <- redraw.component_("MyComponent")
  // Define some hooks.
  let #(state, set_state) = redraw.use_state(0)
  // Return an `Element`. Keep in mind an empty element can be defined
  // with `component_` with `Nil` as props.
  html.div([], [
    html.text("In my component"),
    my_other_component(MyOtherComponentProps),
  ])
}

Allow to compose and use other components within a component. compose is the only way to use components with other components. compose should be called during the bootstrap phase of redraw, and let you access the underlying component.

fn component() {
  use other_component <- redraw.compose(other_component())
  h.div([], [
    other_component(),
    h.div([], []),
  ])
}

context emulates classic Context usage in React. Instead of calling create_context and get_context, it’s possible to simply call context, which will get or create the context directly, and allows to write code as if Context is globally available. context also tries to preserve type-checking at most. context.default_value is lazily evaluated, meaning no additional computations will ever be run.

import redraw

const context_name = "MyContextName"

pub type MyContext {
  MyContext(count: Int, set_count: fn (Int) -> Nil)
}

fn default_value() {
  let count = 0
  les set_count = fn (_) { Nil }
  MyContext(count:)
}

pub fn provider() {
  use _, children <- redraw.component()
  let context = redraw.context(context_name, default_value)
  let #(count, set_count) = redraw.use_state(0)
  redraw.provider(context, MyContext(count:, set_count:), children)
}

pub fn use_my_context() {
  let context = redraw.context(context_name, default_value)
  redraw.use_context(context)
}

context should never fail, but it can be wrong if you use an already used name.

Create a context that components can provide or read. Each context is referenced by its name, a little bit like actors in OTP (if you’re familiar with Erlang). Because Gleam cannot execute code outside of main function, creating a context should do some side-effect at startup.

In traditional React code, Context usage is usually written like this.

import * as react from 'react'

// Create your Context in a side-effectful way.
const MyContext = react.createContext(defaultValue)

// Create your own provider, wrapping your context.
export function MyProvider(props) {
  return <MyContext.Provider>{props.children}</MyContext.Provider>
}

// Create your own hook, to simplify usage of your context.
export function useMyContext() {
  return react.useContext(MyContext)
}

To simplify and mimic that usage, Redraw wraps Context creation with some caching, to emulate a similar behaviour.

import redraw

const context_name = "MyContextName"

pub fn my_provider(children) {
  let assert Ok(context) = redraw.create_context(context_name, default_value)
  redraw.provider(context, value, children)
}

pub fn use_my_context() {
  let assert Ok(context) = redraw.get_context(context_name)
  redraw.use_context(context)
}

Be careful, create_context fails if the Context is already defined. Choose a full qualified name, hard to overlap with inattention. If you want to get a Context in an idempotent way, take a look at context().

Documentation

Create a context that components can provide or read. Because Gleam cannot execute code outside of main function, creating a context should do some side-effect at startup.

In traditional React code, Context usage is usually written like this.

import * as react from 'react'

// Create your Context in a side-effectful way.
const MyContext = react.createContext(defaultValue)

// Create your own provider, wrapping your context.
export function MyProvider(props) {
  return (
    <MyContext.Provider>
      {props.children}
    </MyContext.Provider>
  )
}

// Create your own hook, to simplify usage of your context.
export function useMyContext() {
  return react.useContext(MyContext)
}

In Redraw, creating your application goes through a bootstrap phase, where every component gets created. Your context should be passed at that moment. Find an example with React DOM.

import redraw
import redraw/dom/client

type MyContext {
  MyContext(
    name: String,
  )
}
pub fn main() {
  let assert Ok(root) = client.create_root("#app")
  let context = redraw.create_context_(MyContext(name: "Louis"))
  let app = app(context)
  client.render(root, {
    redraw.strict_mode([
      redraw.provider(context, value, [
        app(AppProps(name: "Lucy")),
      ])
    ])
  })
}

type AppProps {
  AppProps(
    name: String,
  )
}

fn app(ctx: Context(a)) -> redraw.Component(AppProps) {
  use props: AppProps <- redraw.element("App")
  let context = redraw.use_context(ctx)
  html.div([], [
    html.text("Hello " <> props.name <> "!")
    html.text("Hello " <> context.name <> "!")
  ])
}

Documentation

Fragment allow to group children, without creating a node in the DOM.
Documentation

Get a context. Because of FFI, get_context breaks the type-checker. It should be considered as unsafe code. As a library author, never exposes your context and expect users will call get_context themselves, but rather exposes a use_my_context() function, handling the type-checking for the user.

import redraw

pub type MyContext {
  MyContext(value: Int)
}

/// `use_context` returns `Context(a)`, should it can be safely returned as
/// `Context(MyContext)`.
pub fn use_my_context() -> redraw.Context(MyContext) {
  let context = case redraw.get_context("MyContextName") {
    // Context has been found in the context cache, use it as desired.
    Ok(context) -> context
    // Context has not been found. It means the user did not initialised it.
    Error(_) -> panic as "Unitialised context."
  }
  redraw.use_context(context)
}

Get the current value of a ref.

Redraw does not support passing key element to components in an easy way like React does. To simplify this, it uses the same API than Lustre to put keys on children.

fn my_component(props, children) {
  redraw.keyed(my_other_component(props, _), {
    use item <- list.map(children)
    #("my-key", item)
  })
}

Memoizes a Redraw component with children.
Documentation

Memoizes a Redraw component without children.
Documentation

Accepts a Component, and wrapp it in React.memo. React.memo ensures that a component will never repaint when props are identical between two renders. Redraw applies an algorithm suited to Gleam, to avoid you the hard task of comparing props, while providing a correct comparison algorithm.

While such optimisation could be done for every component, being able to select if a component should be memoized or not can help finding and solving bugs. Take a look at the React documentation to get a better idea if you need memoization or not.

pub fn my_component() {
  // Create your other Redraw components before defining the others.
  use my_other_component <- redraw.compose(my_other_component())
  // Define your component.
  redraw.component_("MyComponent", fn (props: MyComponentProps) {
    // Define some hooks.
    let #(state, set_state) = redraw.use_state(0)
    // Return an `Element`. Keep in mind an empty element can
    // be defined with `memoized` with `Nil` as props.
    html.div([], [
      html.text("In my component"),
      my_other_component(MyOtherComponentProps),
    ])
  })
  |> redraw.memoize_
}

Profile allows to measure code performance for a component tree.
Documentation

Wrap your components into a context provider to specify the value of this context for all components inside.
Documentation

Set the current value of a ref, overriding its existing content.

Create a Redraw standalone component, with a name and a render function. Keep in mind this component does not accept children nor props.

Let you update the state without blocking the UI.
Documentation

Strict Mode should be enabled during development.
Documentation

Suspense allow to display a fallback content while waiting for children to finish loading.
Documentation

Convert a React component to a React-redraw component with children. Give it a name, and send directly the FFI. Don’t worry about the snake_case over camelCase, redraw take care of it for you.

Because children can accept anything, it’s up to you to define the type of the children. If you send a List, it will be automatically converted to a JavaScript array.

import redraw

pub type MyComponentProps {
  MyComponentProps(
    first_prop: Bool,
    second_prop: String,
  )
}

@external(javascript, "my_library", "MyComponent")
fn do_my_component(props: MyComponentProps) -> redraw.Component

pub fn my_component() -> fn(MyComponentProps, List(Element)) -> redraw.Component {
  redraw.to_component("MyComponent", do_my_component)
}

Convert a React Component to a Redraw Element. Give it a name, and send directly the FFI. Don’t worry about the snake_case over camelCase, redraw take care of it for you.

import redraw

pub type MyComponentProps {
  MyComponentProps(
    first_prop: Bool,
    second_prop: String,
  )
}

@external(javascript, "my_library", "MyComponent")
fn do_my_component(props: MyComponentProps) -> redraw.Component

pub fn my_component() -> fn(MyComponentProps) -> redraw.Component {
  redraw.to_element("MyComponent", do_my_component)
}

Allow you to update state based on the result of a form action.
Documentation

Async variant of use_transition.
Documentation

Let you cache a function definition between re-renders. dependencies should be a tuple.
Documentation

Let you read and subscribe to context from your component.

Under-the-hood, use_context uses the new use function. This means you can call use_context conditionnally! \

Documentation

Let you add a label to a custom Hook in React DevTools.
Documentation

Let you add a label to a custom Hook in React DevTools, but allow to format it before.
Documentation

Let you defer updating a part of the UI.
Documentation

Let you synchronize a component with an external system.
Documentation

Let you synchronize a component with an external system. Allow to return a cleanup function.
Documentation

Generate unique IDs that can be passed to accessibility attributes.
Documentation

Let you customize the handle exposed as a ref. Use use_imperative_handle when you want to customize the data stored in a ref.
Documentation

Let you customize the handle exposed as a ref. You should probably use use_imperative_handle by default with optional refs.
Documentation

Allow inserting elements into the DOM before any layout Effects fire.

use_insertion_effect is for CSS-in-JS library authors. Unless you are working on a CSS-in-JS library and need a place to inject the styles, you probably want use_effect or use_layout_effect instead.

Documentation

Allow inserting elements into the DOM before any layout Effects fire and allow to return a cleanup function.

use_insertion_effect is for CSS-in-JS library authors. Unless you are working on a CSS-in-JS library and need a place to inject the styles, you probably want use_effect or use_layout_effect instead.

Documentation

Version of useEffect that fires before the browser repaints the screen.
Documentation

Version of useEffect that fires before the browser repaints the screen and allow to return a cleanup function.
Documentation

Let you add a state variable to your component. Allow to create the initial value in a lazy way.
Documentation

Let you add a state variable to your component. Allow to create the initial value in a lazy way. Give an updater function instead of a state setter.
Documentation

Let you cache the result of a calculation between re-renders.
Documentation

Let you optimistically update the UI.
Documentation

Let you optimistically update the UI.
Documentation

Let you optimistically update the UI.
Documentation

Wait for a Promise and returns its content. Uses use under-the-hood. When the Promise is loading, it fallbacks to the nearest Suspense boundary.
Documentation

Let you add a reducer to your component.
Documentation

Let you add a reducer to your component. Allow to initialize the store in a custom way.
Documentation

Let you reference a value that’s not needed for rendering. Most used ref you’ll want to create. They’re automatically created to None, and can be passed to ref prop or use_imperative_handle. Ref are most of the time used to reference DOM node, in order to run side-effects. In this case, you probably don’t want the ref value to be anything than Option(a), unless you need to persist a value across renders which is not part of the DOM. In that case, use use_ref_.
Documentation

Let you reference a value that’s not needed for rendering. Use use_ref if you’re trying to acquire a reference to a child or to a component. Use use_ref_ when you want to keep track of a data, like if you’re doing some side-effects, in conjuction with ref.current and ref.assign.
Documentation

Let you add a state variable to your component.
Documentation

Let you add a state variable to your component. Give an updater function instead of a state setter.
Documentation

Let you subscribe to an external store.
Documentation

Let you update the state without blocking the UI.
Documentation