Leptos mview
An alternative view!
macro for Leptos inspired by maud.
Example
A little preview of the syntax:
use *;
use mview;
async
use *;
use mview;
// fake async function
async
Purpose
The view!
macros in Leptos is often the largest part of a component, and can get extremely long when writing complex components. This macro aims to be as concise as possible, trying to minimise unnecessary punctuation/words and shorten common patterns.
Performance note
Currently, the macro expands to the builder syntax (ish), but it has some performance downsides in SSR mode. This is expected to be fixed with the new renderer in Leptos 0.7
, so I'm not going to make this implementation.
Compatibility
This macro will be compatible with the latest stable release of Leptos. The macro references Leptos items using ::leptos::...
, no items are re-exported from this crate. Therefore, this crate will likely work with any Leptos version if no view-related items are changed.
The below are the versions with which I have tested it to be working. It is likely that the macro works with more versions of Leptos.
leptos_mview version |
Compatible leptos version |
---|---|
0.1 |
0.5 |
0.2 |
0.5 , 0.6 |
0.3 |
0.6 |
Syntax details
Elements
Elements have the following structure:
- Element / component tag name / path (
div
,App
,component::Codeblock
). - Any classes or ids prefixed with a dot
.
or hash#
respectively. - A space-separated list of attributes and directives (
class="primary"
,on:click={...}
). - Either children in braces/parens (
{ "hi!" }
or("hi")
) or a semi-colon for no children (;
).
Example:
mview!
Adding generics is the same as in Leptos: add it directly after the component name, with or without the turbofish.
Note that due to Reserving syntax, the #
for ids must have a space before it.
mview!
Classes/ids created with the selector syntax can be mixed with the attribute class="..."
and directive class:a-class={signal}
as well.
Slots
Slots (another example) are supported by prefixing the struct with slot:
inside the parent's children.
The name of the parameter in the component function must be the same as the slot's name, in snake case.
Using the slots defined by the SlotIf
example linked:
use *;
use mview;
Values
There are (currently) 3 main types of values you can pass in:
-
Literals can be passed in directly to attribute values (like
data=3
,class="main"
,checked=true
).- However, children do not accept literal numbers or bools - only strings.
mview!
- However, children do not accept literal numbers or bools - only strings.
-
Everything else must be passed in as a block, including variables, closures, or expressions.
mview!
This is not valid:
let input_type = "text"; // ❌ This is not valid! Wrap input_type in braces. mview!
-
Values wrapped in brackets (like
value=[a_bool().to_string()]
) are shortcuts for a block with an empty closuremove || ...
(tovalue={move || a_bool().to_string()}
).mview!
-
Note that this always expands to
move || ...
: for any closures that take an argument, use the full closure block instead.mview!
Instead:
mview!
-
The bracketed values can also have some special prefixes for even more common shortcuts!
- Currently, the only one is
f
- e.g.f["{:.2}", stuff()]
. Adding anf
will addformat!
into the closure. This is equivalent to[format!("{:.2}", stuff())]
or{move || format!("{:.2}", stuff())}
.
Attributes
Key-value attributes
Most attributes are key=value
pairs. The value
follows the rules from above. The key
has a few variations:
-
Standard identifier: identifiers like
type
,an_attribute
,class
,id
etc are valid keys. -
Kebab-case identifier: identifiers can be kebab-cased, like
data-value
,an-attribute
.-
NOTE: on HTML elements, this will be put on the element as is:
div data-index="0";
becomes<div data-index="0"></div>
. On components, hyphens are converted to underscores then passed into the component builder.For example, this component:
Can be used elsewhere like this:
mview!
And the
some-attribute
will be passed in to thesome_attribute
argument.
-
-
Attribute shorthand: if the name of the attribute and value are the same, e.g.
class={class}
, you can replace this with{class}
to mean the same thing.let class = "these are classes"; let id = "primary"; mview!
Note that the special node_ref
or ref
or _ref
or ref_
attribute in Leptos to bind the element to a variable is just ref={variable}
in here.
Boolean attributes
Another shortcut is that boolean attributes can be written without adding =true
. Watch out though! checked
is very different to {checked}
.
// recommend usually adding #[prop(optional)] to all these
mview!
// same as...
mview!
See also: boolean attributes on HTML elements
Directives
Some special attributes (distinguished by the :
) called directives have special functionality. All have the same behaviour as Leptos. These include:
class:class-name=[when to show]
style:style-key=[style value]
on:event={move |ev| event handler}
prop:property-name={signal}
attr:name={value}
clone:ident_to_clone
use:directive_name
oruse:directive_name={params}
All of these directives except clone
also support the attribute shorthand:
let color = create_rw_signal;
let disabled = false;
mview!
The class
and style
directives also support using string literals, for more complicated names. Make sure the string for class:
doesn't have spaces, or it will panic!
let yes = move || true;
mview!
Note that the use:
directive automatically calls .into()
on its argument, consistent with behaviour from Leptos.
Special Attributes
There are a few special attributes you can put on your component to emulate some features only available on HTML elements.
If a component has a class
attribute, the classes using the selector syntax .some-class
and dynamic classes class:thing={signal}
can be passed in!
// the `class` parameter should have these attributes and type to work properly
// <div class="my-component extra-class">
mview! ;
It is suggested to only pass in static classes (i.e. with selectors or just a plain class="..."
), as using dynamic classes needs to construct a new string every time any of the signals change; dynamic classes are supported if you want them though.
let signal = new;
// <div class="my-component always-has-this special">
mview!
signal.set;
// becomes <div class="my-component always-has-this">
There is one small difference from the class:
syntax on HTML elements: the value passed in must be an Fn() -> bool
, it cannot just be a bool
.
This is also supported with an id
attribute to forward #my-id
, though not reactively.
// the `id` parameter should have these attributes and type to work properly
// <div id="my-unique-id">
mview! ;
This is also supported on slots by having a class
and id
field with the same attributes and types as the components above.
Children
You may have noticed that the let:data
prop was missing from the previous section on directive attributes!
This is replaced with a closure right before the children block. This way, you can pass in multiple arguments to the children more easily.
mview!
Note that you will usually need to add a *
before the data you are using. If you forget that, rust-analyser will tell you to dereference here: *{monkeys}
. This is obviously invalid - put it inside the braces. (If anyone knows how to fix this, feel free to contribute!)
Children can be wrapped in either braces or parentheses, whichever you prefer.
mview!
Summary from the previous section on values in case you missed it: children can be literal strings (not bools or numbers!), blocks with Rust code inside ({*monkeys}
), or the closure shorthand [number() + 1]
.
Children with closures are also supported on slots, add a field children: Callback<T, View>
to use it (T
is whatever type you want).
Extra details
Kebab-case identifiers with attribute shorthand
If an attribute shorthand has hyphens:
-
On components, both the key and value will be converted to underscores.
let some_attribute = 5; mview! // same as... mview! // same as... mview!
-
On HTML elements, the key will keep hyphens, but the value will be turned into an identifier with underscores.
let aria_label = "a good label"; mview! // same as... mview!
Boolean attributes on HTML elements
Note the behaviour from Leptos: setting an HTML attribute to true adds the attribute with no value associated.
use view;
view!
Becomes <input type="checkbox" checked data-smth />
, NOT checked="true"
or data-smth="true"
or not-here="false"
.
To have the attribute have a value of the string "true" or "false", use .to_string()
on the bool. Make sure that it's in a closure if you're working with signals too.
let boolean_signal = new;
mview!
// or, if you prefer
mview!
Contributing
Please feel free to make a PR/issue if you have feature ideas/bugs to report/feedback :)