ContentKit

Learn how to build components with GitBook’s UI kit

ContentKit is a UI framework allows you to build integrations that work from directly within GitBook. It is used to define interactive layouts for Custom Blocks, Configurations flows and more.

Creating components

Components are created using the createComponent method, which uses a few different options to customize it's behavior. A component represents an element of the UI rendered with specific props and updated through actions impacting its local state.

In addition to creating components, there are a few concepts related specifically to ContentKit and Custom Blocks that will let your integration interact with the rest of GitBook.

The following example displays a button, that when clicked, will return a message in the component's local state that says "Hello world".

import { createIntegration, createComponent } from '@gitbook/runtime';

const helloWorldBlock = createComponent({
    componentId: 'hello-world',
    initialState: {
        message: 'Say hello!'
    },
    action: async (previous, action) => {
        switch (action.action) {
            case 'say':
                return { state: { message: 'Hello world' } };
        }
    },
    render: async ({ props, state }) => {
        return (
            <block>
                <button label={state.message} onPress={{ action: 'say' }} />
            </block>
        );
    }
});

export default createIntegration({
    components: [helloWorldBlock]
});

Define a custom block

Blocks must defined in the integration's manifest file:

blocks:
  - id: hello-world
    title: Hello World Block

All blocks defined in an installed integrations will be listed in the insertion palette for all editors of the space.

Props

Props in ContentKit components are accessed in the render function of your integration. They work similarly to props in React, and help describe the way your component should render.

Props are bound to your component block for all instances.

{
    action: "@editor.node.updateProps",
    props: {
        propMessage: "Props Updated!",
    },
};

State

State in a ContentKit component is a way to keep track of data and information as it changes over time. State is bound locally to a component block, and can be updated by setting the state through an action. It's scoped to only be accessible by the component it's defined in, and works similarly to state in React.

{ 
    state: { 
        stateMessage: "State Updated !" 
    } 
};

Actions

Actions handle events in your component and update its state. See Actions for built-in actions, including @webframe.ready and @webframe.resize, and custom action handling.

Follow Update text with a button to handle an event in your integration.

Component reference

ContentKit provides layout, display, and interactive blocks. Browse the Component reference to find each block’s props and examples.