@spec audio(
  String.t(),
  keyword()
) :: t()

Creates a new audio input.

The input value is a map, with an audio file and metadata:

%{
  file_ref: term(),
  num_channels: pos_integer(),
  sampling_rate: pos_integer(),
  format: :pcm_f32 | :wav
}

Note that the value can also be nil, if no audio is selected.

The file path can then be accessed using file_path/1.

Warning

The audio input is shared by default: once you upload an audio, the audio will be replicated to all users reading the notebook. Use Kino.Control.form/2 if you want each user to have a distinct audio upload with an explicit submission button.

options

Options

• :format - the format to read the audio as, either of:

  • :pcm_f32 (default) - the PCM (32-bit float) format. Note that the binary uses native system endianness. Such binary can be directly converted to an Nx tensor, with no additional decoding

  • :wav

• :sampling_rate - the sampling rate (samples per second) of the audio data. Defaults to 48_000

@spec checkbox(
  String.t(),
  keyword()
) :: t()

Creates a new checkbox.

The input value can be either true or false.

options

Options

• :default - the initial input value. Defaults to false

@spec color(
  String.t(),
  keyword()
) :: t()

Creates a new color input.

The input value can be a hex color string.

options

Options

• :default - the initial input value. Defaults to #6583FF

• :debounce - determines when input changes are emitted. When set to :blur, the change propagates when the user leaves the input. When set to a non-negative number of milliseconds, the change propagates after the specified delay. Defaults to :blur

@spec date(
  String.t(),
  keyword()
) :: t()

Creates a new date input.

The input is read as a %Date{} struct.

options

Options

• :default - the initial input value. Defaults to nil

• :min - the minimum date value

• :max - the maximum date value

@spec file(
  String.t(),
  keyword()
) :: t()

Creates a new file input.

The input value is a map, with a file and metadata:

%{
  file_ref: term(),
  client_name: String.t()
}

Note that the value can also be nil, if no file is selected.

The file path can then be accessed using file_path/1.

Warning

The file input is shared by default: once you upload a file, the file will be replicated to all users reading the notebook. Use Kino.Control.form/2 if you want each user to have a distinct file upload with an explicit submission button.

considerations

Considerations

Note that a file may be deleted in certain cases, specifically:

• when the file is reuploaded
• when used with a form and the uploading user leaves
• when the input is removed

The deletion is not immediate and you are unlikely to run into this in practice, however theoretically file_path/1 may point to a non-existing file.

options

Options

• :accept - the list of accepted file types (either extensions or MIME types) or :any. Defaults to :any

examples

Examples

To read the content of currently uploaded file we would do:

# [Cell 1]

input = Kino.Input.file("File")

# [Cell 2]

value = Kino.Input.read(input)
path = Kino.Input.file_path(value.file_ref)
File.read!(path)

And here's how we could process an asynchronous form submission:

# [Cell 1]

form = Kino.Control.form([file: Kino.Input.file("File")], submit: "Send")

# [Cell 2]

form
|> Kino.Control.stream()
|> Kino.listen(fn event ->
  path = Kino.Input.file_path(event.data.file.file_ref)
  content = File.read!(path)
  IO.inspect(content)
end)

@spec file_path(file_ref) :: String.t() when file_ref: {:file, id :: String.t()}

Returns file path for the given file identifier.

@spec image(
  String.t(),
  keyword()
) :: t()

Creates a new image input.

The input value is a map, with an image file and metadata:

%{
  file_ref: term(),
  height: pos_integer(),
  width: pos_integer(),
  format: :rgb | :png | :jpeg
}

Note that the value can also be nil, if no image is selected.

The file path can then be accessed using file_path/1.

Warning

The image input is shared by default: once you upload a image, the image will be replicated to all users reading the notebook. Use Kino.Control.form/2 if you want each user to have a distinct image upload with an explicit submission button.

options

Options

• :format - the format to read the image as, either of:

  • :rgb (default) - the binary includes raw pixel values, each encoded as a single byte in the HWC order. Such binary can be directly converted to an Nx tensor, with no additional decoding

  • :png

  • :jpeg (or :jpg)

• :size - the size to fit the image into, given as {height, width}

• :fit - the strategy of fitting the image into :size, either of:

  • :contain (default) - resizes the image, such that it fits in a box of :size, but preserving the aspect ratio. The resulting image can be smaller or equal to :size

  • :match - resizes the image to :size, with no respect for aspect ratio

  • :pad - same as :contain, but pads the image to match :size exactly

  • :crop - resizes the image, such that one edge fits in :size and the other overflows, then center-crops the image to match :size exactly

@spec number(
  String.t(),
  keyword()
) :: t()

Creates a new number input.

The input value is can be either a number or nil.

options

Options

• :default - the initial input value. Defaults to nil

• :debounce - determines when input changes are emitted. When set to :blur, the change propagates when the user leaves the input. When set to a non-negative number of milliseconds, the change propagates after the specified delay. Defaults to :blur

@spec password(
  String.t(),
  keyword()
) :: t()

Creates a new password input.

This is similar to text input, except the content is not visible by default.

options

Options

• :default - the initial input value. Defaults to ""

• :debounce - determines when input changes are emitted. When set to :blur, the change propagates when the user leaves the input. When set to a non-negative number of milliseconds, the change propagates after the specified delay. Defaults to :blur

@spec range(
  String.t(),
  keyword()
) :: t()

Creates a new slider input.

The input value can be either float in the configured range.

options

Options

• :default - the initial input value. Defaults to the minimum value

• :min - the minimum value

• :max - the maximum value

• :step - the slider increment

• :debounce - determines when input changes are emitted. When set to a non-negative number of milliseconds, the change propagates after the specified delay. Defaults to 250

@spec read(t()) :: term()

Synchronously reads the current input value.

examples

Examples

input =
  Kino.Input.text("Name")
  |> Kino.render()

Kino.Input.read(input)

@spec select(String.t(), [{value :: term(), label :: String.t()}], keyword()) :: t()

Creates a new select input.

The input expects a list of options in the form [{value, label}], where value is an arbitrary term and label is a descriptive string.

options

Options

• :default - the initial input value. Defaults to the first value from the given list of options

examples

Examples

Kino.Input.select("Language", [en: "English", fr: "Français"])

Kino.Input.select("Language", [{1, "One"}, {2, "Two"}, {3, "Three"}])

@spec text(
  String.t(),
  keyword()
) :: t()

Creates a new text input.

options

Options

• :default - the initial input value. Defaults to ""

• :debounce - determines when input changes are emitted. When set to :blur, the change propagates when the user leaves the input. When set to a non-negative number of milliseconds, the change propagates after the specified delay. Defaults to :blur

@spec textarea(
  String.t(),
  keyword()
) :: t()

Creates a new multiline text input.

options

Options

• :default - the initial input value. Defaults to ""

• :monospace - whether to use a monospace font inside the textarea. Defaults to false

• :debounce - determines when input changes are emitted. When set to :blur, the change propagates when the user leaves the input. When set to a non-negative number of milliseconds, the change propagates after the specified delay. Defaults to :blur

@spec url(
  String.t(),
  keyword()
) :: t()

Creates a new URL input.

The input value can be either a valid URL string or nil.

options

Options

• :default - the initial input value. Defaults to nil

• :debounce - determines when input changes are emitted. When set to :blur, the change propagates when the user leaves the input. When set to a non-negative number of milliseconds, the change propagates after the specified delay. Defaults to :blur

@spec utc_datetime(
  String.t(),
  keyword()
) :: t()

Creates a new datetime input.

The input is editable in user-local time zone, however the value is always read in UTC as a %NaiveDateTime{} struct.

options

Options

• :default - the initial input value. Defaults to nil

• :min - the minimum datetime value (in UTC)

• :max - the maximum datetime value (in UTC)

@spec utc_time(
  String.t(),
  keyword()
) :: t()

Creates a new time input.

The input is editable in user-local time zone, however the value is always read in UTC as a %Time{} struct.

options

Options

• :default - the initial input value. Defaults to nil

• :min - the minimum time value (in UTC)

• :max - the maximum time value (in UTC)